Documentation Structure Entmoot #10

Closed
chrisdickinson opened this Issue May 19, 2015 · 3 comments

Comments

Projects
None yet
5 participants
@chrisdickinson

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:

  1. At the end of the meeting, we should have a proposed documentation structure. This will be in the form of directories (with assumed index landing pages.)
  2. We should agree on a brief set of editorial standards to hold new documentation to for all new docs.

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:

  • Please have read @jacobian's excellent series of posts on technical documentation and editing.
  • Post on this issue any topics that you would like to have documented – ones that you feel are missing!
  • Also suggest other talks/posts you'd like everyone to review before meeting up.
  • Other talks and posts might be added to this list before the conf – check back in!

/cc @Qard @Fishrock123 @mikeal

@Fishrock123

This comment has been minimized.

Show comment
Hide comment

👍

@Qard

This comment has been minimized.

Show comment
Hide comment
@Qard

Qard May 19, 2015

👍

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.

Qard commented May 19, 2015

👍

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.

@danfinlay

This comment has been minimized.

Show comment
Hide comment
@danfinlay

danfinlay Jun 12, 2015

I think even the API docs could use a little love. For example, if you look up the http.createServer method, you get told what event triggers the callback, but there's no link to that event, and the average user is going to have to command-F to find what that means, before they get to the IncomingMessage and responseObject definitions.

I think even the API docs could use a little love. For example, if you look up the http.createServer method, you get told what event triggers the callback, but there's no link to that event, and the average user is going to have to command-F to find what that means, before they get to the IncomingMessage and responseObject definitions.

@thomblake thomblake closed this Jun 13, 2016

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment