Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Documentation Structure Entmoot #10
I'd like to see Node's documentation get better. While we currently have fairly complete and well-written API reference docs, we're missing a lot of other docs: tutorials, topic guides, internal documentation, navigation, policies, etc. One clear sign that things could be better is that we're running out of places to put this info – some of it's going into project wikis, some of it is being shoved into ALLCAPS.md files at project root. Often the topics these docs touch on cross over – CONTRIBUTING.md + COLLABORATORS.md comes to mind! We need good docs, and the first step in that is having a good structure – one that can address our information storage needs for the future.
I've been a part of several documentation efforts over the years – there's a lot of enthusiasm for writing good documentation, but that enthusiasm is often hard to direct. I'd like to propose some specific goals for this meeting:
We want to have just enough agreement on direction that we can get ourselves out of the way and let everyone pitch in. If we reach these goals, we can propose the new structure on the Node issue tracker, and start dividing up the work of creating this documentation at that point.
Before the meeting:
I'm really interested in improving contributor docs. The CONTRIBUTING.md and COLLABORATOR_GUIDE.md we currently have do a great job of covering the process, but don't really get into how the actual code works.
Some aspects of the code already have documentation in one form or another somewhere but people may not be aware of them. I'll compile a list of a few things here, but we should work toward integrating these somehow into the contributor introduction/reference docs.
I think even the API docs could use a little love. For example, if you look up the