How do I add a community document?

A community document is a living document that represents a community effort to discuss a question or idea. We call it "living" because we encourage community members to edit and contribute to the documents over time, and so there isn't a "publish" data associated with it. For this reason, we use this wiki associated with the repository here. if you ever need to clone this content, you can do:

$ git clone [email protected]/USRSE/usrse.github.io/wiki

During the testing phase of the living documents, the wiki will only be editable by community (repository) members, however we might open this up to include others as well.

1. How do I edit an existing document?

To edit a living document that exists, you can browse the wiki here to update it. You can generally click on the page, and then click the "Edit" button to work on, preview, and then save your work. Be sure to add a meaningful message to the change so that others can understand the contribution.

2. How do I start a new document?

If you want to add a new document, while you might add it directly to the wiki, it's recommended to get others involved first. You can ping others in the USRSE slack to contribute, and you might even start the document as a Google Doc for easier commenting and editing, and then move to the wiki when it's in a final first draft state. For all community documents, the following points apply:

1. It's strongly suggested to first work on your document in Google Docs or similar, where you can bring in multiple community members to put together a first draft. Importantly, you should make sure that the content adheres to the US-RSE Code of Conduct. It is suggested that you have discussion and work on the document with at least two other community members before submitting the document to the wiki. You should feel that it's in a solid "first draft state" before doing a submission.
2. Make sure that you verify the following:

• the content is of interest to the RSE community
• the content does not violate the Code of Conduct.

NOTE: Any material added to the wiki that does not follow these rules is subject to removal. If you see content on the wiki that is not appropriate or otherwise breaks these rules, please open an issue on the repository immediately, or contact the steering committee.

If you want to start a community document and would like some help or to talk with others, we encourage you to post on the US-RSE slack or write an issue on the repository here. To add your document, the easiest thing to do is to add the link to it from the home page first. If you look at the Home page, you'll see a flat list of topics above the User Guide, with each topic having a list of community documents. You can add a link to your new document until an existing topic, or add a new header (at the same nesting level) with a new topic of your choice. For all pages on the wiki, the community document title will correspond to the name you choose in the link. For example, if you want the title to be "My Awesome Post" then your link should look like:

[My Awesome Post](My-Awesome-Post)

The dashes won't be present in the title, however the capitalization will be maintained. If you need any help with these steps, please open an issue or ping someone on slack.

If you otherwise want to start a community document and would like some help or to talk with others, we encourage you to post on the USRSE slack or write an issue here.