Docs: separate reference docs and prose?

[August Lilleaas]

Hi folks,

I've been reading a lot of docs lately, and I think I've come to the conclusion that I prefer docs that separate prose and reference. For example, Datomic only has prose. So does Faye. The prose is great, but for me it's not enough. I would very much like to have a page that lists everything a module can do.

Should we have this separation in Buster? The reason I'm suggesting this is that we haven't yet settled on a method for generating comment based docs, partly because it's proving difficult to generate the sphinx formatted docs in a way that we want. For example, having an argument name be a link to another module's documentation.

If we do separate it, the generated API docs can be a completely separate thing. This will be similar to Lucene, prose and API docs are two separate things. I don't think the difference in visuals and layout is a problem, I actually think it's a benefit. Navigatin API docs is very different from navigating prose anyways.

[Christian Johansen]

Hi,

I've been reading a lot of docs lately, and I think I've come to the conclusion that I prefer docs that separate prose and reference. For example, Datomic only has prose. So does Faye. The prose is great, but for me it's not enough. I would very much like to have a page that lists everything a module can do.

I agree that having a page that lists everything a module can do is great. But I don't see why that can't be the bottom half of a page that starts with prose style documentation. If we add an anchor, like a consistent #reference, then it's easily linkable too. Additionally we get the benefit of having all documentation for a module in one place.

The way I imagine the docs is roughly one page per NPM module. The top of the page is instructional prose that covers 80-90% of use-cases. This would be extracted from the project's Readme. The latter half of the page will be an API reference.
 

Should we have this separation in Buster?

I'm really keen on trying the "all in one page" approach properly first.
 

The reason I'm suggesting this is that we haven't yet settled on a method for generating comment based docs, partly because it's proving difficult to generate the sphinx formatted docs in a way that we want. For example, having an argument name be a link to another module's documentation.

I wasn't aware that we had even tried doing this? As far as I can remember, we discussed with Stein Magnus (jodal) how to do this, have a loose plan, and will attempt executing on it when jodal is back in business. Please correct me if I'm missing something.
 

If we do separate it, the generated API docs can be a completely separate thing. This will be similar to Lucene, prose and API docs are two separate things. I don't think the difference in visuals and layout is a problem, I actually think it's a benefit. Navigatin API docs is very different from navigating prose anyways.

I think splitting the docs will hurt findability the most. Since each module will have essential information in more than one place, it will be harder to decide which one to link to in various places, people may not remember which source they found some valuable piece of information, people may be frustrated to find API docs when they're looking for prose (failing to realize the prose is elsewhere).

Not a huge point, but worth noting that the general trend in the JavaScript community seems to be one-page docs. Examples:

http://underscorejs.org/
http://backbonejs.org/
http://zeptojs.com/
http://visionmedia.github.com/mocha/

--
MVH
Christian