Skip to content
This repository has been archived by the owner on Nov 21, 2018. It is now read-only.

Documentation Tooling #99

Closed
chrisdickinson opened this issue Jan 22, 2015 · 8 comments
Closed

Documentation Tooling #99

chrisdickinson opened this issue Jan 22, 2015 · 8 comments

Comments

@chrisdickinson
Copy link

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
Copy link
Contributor

mikeal commented Jan 22, 2015

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
Copy link
Contributor

zeke commented Jan 22, 2015

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
Copy link
Author

@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
Copy link
Contributor

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
Copy link
Contributor

Related to #23

+1

@robertkowalski
Copy link

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

@mikeal
Copy link
Contributor

mikeal commented Jan 29, 2015

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
Copy link
Author

Next steps are here.

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests

7 participants