search

Code-dot-mil / code.mil

An experiment in open source at the Department of Defense.
https://www.code.mil
MIT License
1.28k stars 122 forks source link

Add documentation on how to do good OSS documentation #240

Open jordangov opened 5 years ago

jordangov commented 5 years ago

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.

jbjonesjr commented 5 years ago

helpful resource: http://opensource.guide/home/

jbjonesjr commented 5 years ago

also i have a bunch of stuff here: https://github.com/jbjonesjr/open-source-docs YMMV

jordangov commented 5 years ago

w00t! Thanks Jamie. Ya know, PRs welcome as well. ;)

jbjonesjr commented 5 years ago

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. 😉

jotasprout commented 5 years ago

I'd love to bring my tech writing experience and help out with this.

jordangov commented 5 years ago

I think this is related to #180, it's all about how to maintain an OSS project.

jotasprout commented 5 years ago

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 commented 5 years ago

@jordangov Is it okay to combine these?

jordangov commented 5 years ago

Fine by me

jotasprout commented 5 years ago

Working on this and #180 today.

jotasprout commented 5 years ago

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?

jordangov commented 5 years ago

Suggest something! We're pretty open, and will comment if it doesn't look right.

jotasprout commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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)

GrooveCS commented 3 years ago

Is this still an Open Issue?