How to write documentation #244
Conversation
Includes guidance for README and CONTRIBUTING pages, standards for Issues and Pull Requests, and instructions for applying and creating labels for issues. Resolves: Code-dot-mil#180, Code-dot-mil#240
|
Thanks @jotasprout! I'll try to review this coming week (along with @jgarber623-gov hopefully). Just as an FYI, we deploy PR preview URLs, so you can see this at: https://deploy-preview-244--code-mil.netlify.com/ |
| @@ -0,0 +1,70 @@ | |||
| # Writing Good Documentation | |||
There was a problem hiding this comment.
Hmm... why is this txt file here? Was this leftover in a commit somehow? Seems duplicative.
|
|
||
| Your README is the first impression your project makes. Like any other "above the fold" content on a website home page, this is where visitors make the decision to user either the scrollbar or the Back button. You must simultaneously greet visitors with a smile and give your project's elevator pitch. | ||
|
|
||
| - Describe your app's purpose |
There was a problem hiding this comment.
Let's change this from "app" to "project" (some of our stuff isn't really "apps")
| Your README is the first impression your project makes. Like any other "above the fold" content on a website home page, this is where visitors make the decision to user either the scrollbar or the Back button. You must simultaneously greet visitors with a smile and give your project's elevator pitch. | ||
|
|
||
| - Describe your app's purpose | ||
| - Provide basic instructions for use. |
There was a problem hiding this comment.
Probably need to expand on this... "use" is a bit vague?
There was a problem hiding this comment.
I'm thinking: what sections typically go in here? What should they say?
| - Provide links and explanations for other documentation you may have such as a CONTRIBUTING.md file, tutorials, other .md files for individual sections of a relatively large project, and to an online demo or the live app itself. | ||
| - Include screenshots -- if, for no other reason, to liven it up visually. | ||
|
|
||
| ## Writing a Good CONTRIBUTING.md |
There was a problem hiding this comment.
Need a lot more in this section. Things like:
- are there tests you should run?
- what should go in an issue?
- what is the review process?
- do I need to sign a DCO or add my name to some list?
- legal things?
|
|
||
| You might provide contact info for questions when opening an issue isn't appropriate. | ||
|
|
||
| ## Writing Issues and Comments |
There was a problem hiding this comment.
Let's mention that maintainers should create an issue template (and link to how to do that on GH)
|
|
||
| ### Applying Labels While Creating a New Issue | ||
|
|
||
| While creating a new issue under the Issues tab, click the Labels button (looks like a Settings button or a gear) on the right and choose a label from the menu. |
There was a problem hiding this comment.
This is very GH specific... I think we take this section out.
|
|
||
| <img width="500" height=auto src="https://github.com/jotasprout/code.mil/blob/how-to-write-documentation/src/assets/images/documentation/labelingNewIssue.png"> | ||
|
|
||
| ### Applying Labels to Existing Issues |
There was a problem hiding this comment.
Similar to above, let's nix this one
|
|
||
| <img width="500" height=auto src="https://github.com/jotasprout/code.mil/blob/how-to-write-documentation/src/assets/images/documentation/labelMenu.png"> | ||
|
|
||
| ### Creating and Applying Custom Labels |
There was a problem hiding this comment.
This is good, but we need to take away the GH-specific aspect. Can we look at some other services and generalize this?
|
|
||
| ### Tips | ||
|
|
||
| - Provide guidelines for respect, courtesy, etc. in CONTRIBUTING.md or a "Code of Conduct" file. |
There was a problem hiding this comment.
This item is great, but not really a "tip" for issues IMO. Can we break this out into it's own thing?
| - Provide guidelines for respect, courtesy, etc. in CONTRIBUTING.md or a "Code of Conduct" file. | ||
| - If your project uses multiple languages and skills, you might mention which specific language a potential contributor needs to work on this skill. Otherwise, they may start a task they expect only requires HTML and Javascript but quickly realizes they need some Ruby knowledge or something else the lack of which turns a "small" and "easy" issue into something prohibitive and discouraging. | ||
|
|
||
| ## Reviewing Pull Requests |
There was a problem hiding this comment.
This is good, but let's expand this a bunch... why is this important? What should they look for?
There was a problem hiding this comment.
Ah... I see you have that below a bit... can we expand anyway?
|
@david-saeger Why did we close this PR? Seems like at least a start to resolve #240 and #180? I see I made a bunch of comments previously, but could we not use this PR as the base to solve these issues? |
|
Im game to open it again. Didnt see any of your comments responded to and it had been a couple years so figured it the conversation was more than stale. |
Yeah, it's definitely stale. But still might be a good starting point. Someone else (you? me? Nick?) could certainly address the comments and wrap this one up. |
|
Sorry I didn't respond to the comments -- but I just saw the email about the latest one. I'll review the feedback, work on it, and report back ... unless someone else is doing it. May I? |
@jotasprout No worries... it was a long time ago. :) FYI, I no longer run the site, but happy to review content. @david-saeger is the gatekeeper now! |
Issue:
Approach
Created How to Write Documentation page (for issue #240 ) including section on using labels (for issue #180 ) . Still working on it but looking for feedback and direction.