code.mil icon indicating copy to clipboard operation
code.mil copied to clipboard

Published 20 hours ago • verified publisher icon Code-dot-mil

Add documentation on how to do good OSS documentation

Open jordangov opened this issue 6 years ago • 17 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.

jordangov avatar Sep 06 '18 14:09 jordangov

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

jbjonesjr avatar Sep 06 '18 14:09 jbjonesjr

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

jbjonesjr avatar Sep 06 '18 14:09 jbjonesjr

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

jordangov avatar Sep 06 '18 14:09 jordangov

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

jbjonesjr avatar Sep 07 '18 00:09 jbjonesjr

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

jotasprout avatar Sep 20 '18 20:09 jotasprout

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

jordangov avatar Sep 23 '18 13:09 jordangov

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 avatar Sep 26 '18 16:09 jotasprout

@jordangov Is it okay to combine these?

jotasprout avatar Oct 03 '18 15:10 jotasprout

Fine by me

jordangov avatar Oct 03 '18 16:10 jordangov

Working on this and #180 today.

jotasprout avatar Oct 08 '18 14:10 jotasprout

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?

jotasprout avatar Oct 08 '18 18:10 jotasprout

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

jordangov avatar Oct 09 '18 13:10 jordangov

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.

jotasprout avatar Oct 09 '18 14:10 jotasprout

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?

jordangov avatar Oct 09 '18 14:10 jordangov

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.

jotasprout avatar Oct 09 '18 15:10 jotasprout

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)

jordangov avatar Oct 09 '18 16:10 jordangov

Is this still an Open Issue?

GrooveCS avatar Sep 01 '20 15:09 GrooveCS