Repository navigation
Add documentation on how to do good OSS documentation #240
Description
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.
Activity
jbjonesjr commentedon Sep 6, 2018
helpful resource: http://opensource.guide/home/
jbjonesjr commentedon Sep 6, 2018
also i have a bunch of stuff here: https://github.com/jbjonesjr/open-source-docs YMMV
jordangov commentedon Sep 6, 2018
w00t! Thanks Jamie. Ya know, PRs welcome as well. ;)
jbjonesjr commentedon Sep 7, 2018
don't want to take away from that great
help wantedopportunity.and anyway, i already signed myself up to make a new code.gov API client, so i'm
contributed outright now. 😉jotasprout commentedon Sep 20, 2018
I'd love to bring my tech writing experience and help out with this.
jordangov commentedon Sep 23, 2018
I think this is related to #180, it's all about how to maintain an OSS project.
jotasprout commentedon Sep 26, 2018
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.
jotasprout commentedon Oct 3, 2018
@jordangov Is it okay to combine these?
jordangov commentedon Oct 3, 2018
Fine by me
jotasprout commentedon Oct 8, 2018
Working on this and #180 today.
jotasprout commentedon Oct 8, 2018
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?
docs: Adds How to Write Good OSS Documentation page
jordangov commentedon Oct 9, 2018
Suggest something! We're pretty open, and will comment if it doesn't look right.
jotasprout commentedon Oct 9, 2018
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.
jordangov commentedon Oct 9, 2018
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?
jotasprout commentedon Oct 9, 2018
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.
jordangov commentedon Oct 9, 2018
Ah, yeah...
So all of the main nav is specified in the
_datadirectory: https://github.com/Code-dot-mil/code.mil/blob/master/src/_data/navigation.ymlBut 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)
GrooveCS commentedon Sep 1, 2020
Is this still an Open Issue?