-
Notifications
You must be signed in to change notification settings - Fork 6
Contributing by Writing
Hello and thank you for your desire to help to write the AguaClara textbook. This page contains everything you need to know to get started. This wiki page assumes that people who are writing to the textbook are AguaClara students and have a working knowledge of GitHub.
You can go to the Projects tab in this repository, found here, to see what's currently going on in Textbook land. The files that make it onto the official textbook site are organized within the projects and are labeled with "Chapter: __________". Open one of the Chapter:________ projects and you'll see various columns. Items in a column are usually either GitHub issues or Pull Requests (PRs) relating to a particular file within that chapter. Each issue serves as a documentation hub for the document. The different columns that you'll see in any given project are listed below:
- To do: Documents that have not been been created or that have been created but do not yet have any content.
- Started: Documents that are being added to. Still in the content creation phase
- Currently in Progress: Documents that are PRESENTLY being worked on. As in, right now! This means someone is working on this document as you look at it in the projects page. To prevent messy merge conflicts, multiple people should not work on the same document at the same time. You can communicate your thoughts via the document's issue!
- Needs Review: Draft of document has been finished. Reviewers can now pick it up and add comments to the issue page.
- Reviewer Approved: Document has been commented on by at least 3 reviewers and those comments have been addressed. More reviewers can still pick up these documents. I believe the applicable philosophy is "the more the merrier!"
- Done: No document is ever truly done. Therefore this column is only for closed organizational/functionality related issues.
As you work on documents, you should move the issues and PRs to the relevant columns in the project you're working on to let everyone know what you're up to. Additionally, assign people or yourself to documents that you are involved in via the issue page.
When you decide to begin working on a document, immediately create a branch and name it the name of the document you're working on without the file extension. For example, if you were to be working on FCM_Design.rst, your branch would be called FCM_Design. Create a PR for this branch and place it in the same column as its respective issue in the Projects tab. Finally, assign yourself to the issue. Now you can work on this file in peace, knowing that other writers can support you and view your work!
To ensure that every build of the AguaClara textbook is passing, every PR must be approved by at least one other writer and is automatically vetted by GitHub Actions. Once you are content with your work in a document and at least one reviewer and GH Actions have approved of your PR, it can be merged into master.
It is imperative that you read both this guide about how to get your environment setup to work on the textbook and this guide about writing in RST and following AguaClara textbook convention when writing.
Reading both of those guides and this wiki page thoroughly and understanding them is critical to making sure that all of your work is done well and incorporated effectively into the book.