Integration with narrative docs

[tmcw]

JSDoc has a tutorials system as a sort of sidecar to docs.

This one cuts both ways:

• Narrative docs are a must-have alongside API docs
• There are many other systems that are great and geared towards narratives, like Jekyll and GitBook
• Linking to narrative docs and packaging them in a reasonable manner is a top priority

Examples:

• https://github.com/lxbarth/docfish

Requirements?

• translations?

[tmcw]

/cc @lyzidiamond @lxbarth

Would love to scope out what the needs around non-API documentation here, and what we can do to recommend or build a path. documentation is trying to knock the idea of API docs (the kinds of docs we currently maintain in API.md) out of the park, but narrative docs need love too, and at least to my eyes, are a less explicit usecase that can have a lot of different narratives.

[lxbarth]

My goal with docfish is to provide a multilingual site generator for narrative docs that is easy to contribute to and easy to lift from.

• Multilingual (because)
• Markdown-only documents (this is robust, portable and easy to edit anywhere)
• Very simple document structure
• Still relies on Github for CRUD. This is a hurdle for some, but I think fine as it saves huge complexity.

@planemad and I are planning on giving docfish a try in production with Mapbox' multilingual OSM guides that we'd like to publish soon.

[lyzidiamond]

I'm not sure what you're going for here, but I can try to provide something...

Narrative documentation I think seeks to answer three main questions:

1. What is this tool/library/widget?
2. What problems does it solve?
3. How can I use it to solve those problems?

The question is, what's the best framework for a) identifying those problems and b) explaining how to solve them. Tutorials can be helpful for this, but don't really get all the way to the finish line.

[schmod]

I support this feature! API docs are great, but not sufficient for most of us.

We don't want to re-invent the static site generator from scratch, but there seem to be surprisingly few options for quickly generating attractive documentation sites from a pile of Markdown files, particularly if you want the tool to fit into the node toolchain, and don't want to write a ton of configuration. Beautiful Docs seems to be the only major contender.

The big question is if we want to make this a completely separate project. There's a lot to be said for keeping documentation as simple as possible.

[montogeek]

Hi!

I want to contribute to made the documentation of this project on GitBook, at this moment is hard to follow the Markdown files.

How can I help?

[tmcw]

888f5ec implements the narrative style & structure, and https://www.mapbox.com/mapbox-gl-js/api/ is the main current public demo of it. Remaining step is to tag a real release, be happy with the theme, and document it.