Code-dot-mil/code.mil

Add documentation on how to do good OSS documentation

Open

#240 opened on Sep 6, 2018

View on GitHub
 (17 comments) (0 reactions) (0 assignees)JavaScript (1,238 stars) (115 forks)batch import
[effort] small[issue-type] content[skill-level] beginnercode.govhelp wanted

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.

Contributor guide

Tech stack
None
Domain
documentation
Issue type
feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
stale
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
Familiarity with open source practicesWriting skills
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
70
Research direction
Review the existing 'how to open source.html' page at https://www.code.mil/how to open source.html and the contributing guidelines. Examine comments in the issue for specific suggestions. Propose a list of sections and write a draft. Ensure to align with the repository's documentation style.
Add documentation on how to do good OSS documentation · Code-dot-mil/code.mil#240 | Good First Issue