Add documentation on how to do good OSS documentation
jordangov opened this issue · comments
Feature
We would like to have better documentation on how to create good open source software documentation as guidance for Department organizations wishing to open source things. This should include things like relevant sections of a "contributing" doc (not just a link to an example), how to write and review PRs, good commit messages, how to write a good GH issue, etc.
Page(s) Affected
This could go on https://www.code.mil/how-to-open-source.html ("How to Open Source"), but it could live on it's own page, linked a couple of places.
helpful resource: http://opensource.guide/home/
also i have a bunch of stuff here: https://github.com/jbjonesjr/open-source-docs YMMV
w00t! Thanks Jamie. Ya know, PRs welcome as well. ;)
don't want to take away from that great help wanted opportunity.
and anyway, i already signed myself up to make a new code.gov API client, so i'm contributed out right now. 😉
I'd love to bring my tech writing experience and help out with this.
I think this is related to #180, it's all about how to maintain an OSS project.
Okay. I'd like to take this and #180 on simultaneously so I can work on them together since issue 180 will be a part of this issue.
@jordangov Is it okay to combine these?
Fine by me
Working on this and #180 today.
Where will this writing-good-documentation page live in the site? Where do there need to be links to it? Might it fall between "How to Open Source" and the FAQ in the nav?
Suggest something! We're pretty open, and will comment if it doesn't look right.
I like the idea of having it "beneath" How To Open Source with a similar submenu -- how do you do that with YAML? I could copy and alter the one for HTOS if you can direct me to it.
Hmm... I think this is a lot of content to nest "beneath" How to Open Source. In any case, that's a single page with jump links, and I think this would be a separate page, right?
I don't mean inside the How to Open Source menu as a sub-item ... I mean between "How to Open Source" and the FAQ in the left nav (beneath HTOS and above FAQ) ... so it would be a separate page with jump links of it's own.
Ah, yeah...
So all of the main nav is specified in the _data directory: https://github.com/Code-dot-mil/code.mil/blob/master/src/_data/navigation.yml
But the side subnav is specified in the page's md file itself (see the top of the "How to Open Source" page: https://github.com/Code-dot-mil/code.mil/blob/master/src/how-to-open-source.md)
Is this still an Open Issue?