[Discuss] Living documentation in Kibana

[stacey-gammon]

Tested Demos & Tutorials in Kibana

Proposal

Working, interactive, tested demos of services and extension points, with tutorials, using real extracted code snippets.

Goals

1. Make it as easy as possible for developers to learn how to write custom plugins.
2. Easy as possible for developers to write tutorials.
3. Use real code snippets that are tested to ensure that we don't accidentally show invalid code examples.
4. Avoid duplicate sources of truth, especially with regard to [discuss] Future of Developer Documentation #41833

Details

I've gone around in circles on whether these tutorials should be built inside Kibana, or rather integrated with the api-extractor. Where I am at the moment is that it would be a much larger effort to integrate into the api-extractor, and also that these are really different types of documentation. One is documenting the public apis, another is step by step tutorials.

So, while I could swing back the other way, right now I'm planning to move forward with tutorial documentation inside Kibana, which can be linked to by the api-extracted documentation.

Steps

How can we break this down into small steps?

1. A single command to run all demo plugins in Kibana: yarn start --run-demos which just adds all the various --plugin-paths and --no-base-path.

2. Sdd ability to extract code references.

3. Add a pluggable tutorial app in plugin_functional that has these tutorials. The demos can optionally live side by side these tutorials, or they can use links to navigate the user to the working demo. The benefit of having the demo outside the tutorial is that the code snippets are likely more real-life scenarios - e.g. the extension points will be available on AppMountContext, not passed through a custom context that the tutorial app is using.

4. Build tutorials with code snippets and demos either linked or embedded.

Related links

• The future of developer documentation

[timroes]

I totally like and support that idea. I wonder how you see the correlation towards actual JSDoc, API documentation? For me it would make sense to have this in that same system so that you could also just click on any method call in the code and see the API documentation for that directly. I would at some point maybe even suggest enabling that --run-demos automatically when you're running in --dev mode, since you're anyway having the Kibana you want to develop running that way, so imho it would make also sense having the documentation and examples available constantly.

The demos can optionally live side by side these tutorials, or they can use links to navigate the user to the working demo.

I think it could make sense having them living beside. Maybe the demos themselves are not linked in the navigation on the right, but you can have a link in each of the tutorials to "Full example (app)" which links you to the demo application (which would then also be the one tested via functional tests?).

[stacey-gammon]

I wonder how you see the correlation towards actual JSDoc, API documentation? For me it would make sense to have this in that same system so that you could also just click on any method call in the code and see the API documentation for that directly.

I've gone round and round on this. I started to investigate writing the tutorials in the API documentation but I don't think this is the right place for the tutorials. A step by step tutorial would be structured totally different than the API documentation, so I think we could create a UI that works best for each. It's also a bit awkward where each tutorial would be in the API Docs (if built as part of that) -- there is only one packageDocumentation which could potentially cover a lot of tutorials. Can't put them in the demo code because the api-extractor is built to parse exported APIs and the demo code isn't exporting any apis - it's just using them.

As far as how to connect the api docs and the tutorial docs, I think they should link to each other. Tutorial docs would have something like "learn more about this apis [here](http://github.com/elastic/kibana/dev/docs/.... or maybe http://elastic.co/docs/dev/...), while the api docs would say "Explore this [tutorial](http://localhost:5601...) to learn more (like our View in Console links work in the elasticsearch CURL examples.). with a note about making sure you are running Kibana with the --run-demos flag.

The tutorial docs could also theoretically be hosted online somewhere, even in asciidoc. But I don't want it to be written in asciidoc, but parsed into asciidoc, so we can continue to use the real code snippets. Right now, the shortest path to getting something up and running is to do all this in Kibana, but ultimately it'd be nice to parse this information into a json like the api-extractor has api.json, it could be tutorials.json, then we can host it anywhere, and the source of truth stays the same. But writing a custom parser and asciidoc builder is to time consuming atm, imo, I'd rather just build in Kibana. I think there is some benefit to hosting locally. The audience will be developers, they will likely already be running Kibana. There is also benefit to hosting online somewhere - discoverability / search-ability.

Maybe the demos themselves are not linked in the navigation on the right, but you can have a link in each of the tutorials to "Full example (app)"

Yea, the one issue with having the demos hosted inside the tutorial documentation is that it actually changes the reference code - e.g. if the demo is hosted in an app it gets stuff from AppMountContext, if it's a section inside the demo tutorials, it'll be retrieved differently.

[stacey-gammon]

You can now run these examples via yarn start --run-examples. I think the only thing left that would be nice is to have a single plugin with links/descriptions to all the explorer apps.

[stacey-gammon]

Developer examples app was added, with searchable links/descriptions to the specific examples.