Documentation Tooling

[chrisdickinson]

If this WG is interested, I'd like to explore having it take over ownership of the documentation tooling for io.js. There's a natural intersection of concerns: localization, HTML generation, hosting, versioning, and the desire for smaller, sub-working-groups to be able to use the tooling provided.

While the docs themselves would still live in iojs/io.js; out/doc would be generated by whatever tool this WG deemed fit, whether it was custom built or a separate project. The tool would have to be a good basis for documentation going forward, and should support:

• At least the same level of quality for API docs.
• Documentation not tied specifically to a single API – that is to say, while we largely succeed at reference material, we fail at providing tutorial and overview docs.
• The ability to switch between versions of the docs.
• The ability to author and switch between localizations of the docs.

Things I'm not super interested in supporting via this tool:

• Directly editing non-human-oriented authoring formats (i.e., JSON).
• Generated API docs (like JavaDoc).
• Doctests.
• Type annotation.

Is there interest in this? The concrete steps going forward are to fully rip the existing tool out of the makefile, and point the makefile at the doc-tool repo instead.

[mikeal]

While the docs themselves would still live in iojs/io.js; out/doc

Is there a reason the output has to live in io.js? I know why we would want the data to live there (so that we can sync API changes to doc changes) but it seems like the generated and served documentation could live elsewhere. Just a thought.

[zeke]

We are solving a similar problem at npm. The docs.npmjs.com site aggregates content from disparate places, namely the docs within npm/npm. Details: https://github.com/npm/docs.npmjs.com#editing-content

[chrisdickinson]

@mikeal I was using that as a shorthand for "the documentation tool will have complete control over the docs directory" – there's no reason it couldn't be made to output elsewhere.

@zeke rad! I'll take a look at this. Thanks for the link.

[snostorm]

I really like this idea, especially in keeping a streamlined brand/feel between the main website and API docs. I really like having a "Guides" section to compliment the API docs and being able to cross-link, etc. a little easier would be nice.

At the very least, short term, it would be cool to have the website's navigation header stay when entering the API Docs section. 👍

[therebelrobot]

Related to #23

+1

[robertkowalski]

hey i would like to join forces with you, please send me an invite to your next meeting, i am rok@kowalski.gd

[mikeal]

For reference, @isaacs brought up in the TC meeting that Robert is building a doc generator already that could easily also replace the one we currently use for node's docs so it would be good to bring him in to the working group and combine our efforts :)

[chrisdickinson]

Next steps are here.