Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation Structure Entmoot #10

chrisdickinson opened this issue May 19, 2015 · 3 comments

Documentation Structure Entmoot #10

chrisdickinson opened this issue May 19, 2015 · 3 comments


Copy link

@chrisdickinson chrisdickinson commented May 19, 2015

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 files at project root. Often the topics these docs touch on cross over – + 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

Copy link

@Fishrock123 Fishrock123 commented May 19, 2015


Copy link

@Qard Qard commented May 19, 2015


I'm really interested in improving contributor docs. The and 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.

Copy link

@danfinlay danfinlay commented 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
5 participants
You can’t perform that action at this time.