Generating docs in the static website era

Since the mid-90's not much have changed on the documentation generator space. Tools like javadoc are still equal to themselves useful but not very flexible. Let's see what we can now do by mixing both documentation generators and static website generators.

Transcript

1. Alexandre Stanislawski Generating docs in the static website era Software engineer / Algolia Public @bobylito bobylito
2. About me > Software engineer at Algolia > Lead of InstantSearch.js > Side topic: docs of our main libraries #AlgoliaSearchParty @bobylito Documentation in the static website era
3. Dedicated documentation team DocSearch (React, vue.js, Laravel…) Main libraries have their documentation websites Algolia + docs = <3 #AlgoliaSearchParty @bobylito Documentation in the static website era
4. #AlgoliaSearchParty @bobylito And now a little story
5. Documentation in the static website era 2015: InstantSearch.js v1 #algoliaSearchParty @bobylito
6. Documentation in the static website era Jekyll was cool #algoliaSearchParty @bobylito
7. Documentation in the static website era JsDoc less so #algoliaSearchParty @bobylito
8. > the tool > the annotations in the code jsDoc: 1 word, two things #algoliaSearchParty @bobylito Documentation in the static website era
9. Documentation in the static website era > Exhaustivity: all annotations are translated into doc > Collocation: doc lives with the code Reasons for keeping annotations #algoliaSearchParty @bobylito
10. Documentation in the static website era Documentation generators (like JSDoc) are the ancestors of static website generators They do the same for docs than Jekyll does for blogs. Before it was cool... #algoliaSearchParty @bobylito
11. Documentation in the static website era > poor / unique templating system > no css preprocessor > no modern js stack And they haven’t aged well #algoliaSearchParty @bobylito
12. Documentation in the static website era Applies a theme to output HTML and CSS #algoliaSearchParty @bobylito Integrate the JSDoc in Jekyll? Extracts the comments in the code Organizes the comments Export as markdown Documentation generator
13. Documentation in the static website era #algoliaSearchParty @bobylito Not the only one!
14. Documentation in the static website era 1. A script generates markdown files from *.js 2. The markdown can then be integrated to Jekyll And in our case, we used jsdoc-to-markdown Our solution #algoliaSearchParty @bobylito
15. #AlgoliaSearchParty @bobylito
16. Let’s fast forward to now #AlgoliaSearchParty @bobylito
17. Documentation in the static website era > Metalsmith ◦ Not focussed on blogs ◦ Written in JS ◦ Easy to build plugins > PUG + Sass (+ webpack + handlebars) > And a custom plugin for documentation.js Using modern tools for docs #algoliaSearchParty @bobylito
18. Documentation in the static website era Applies a theme to output HTML and CSS Bypassing the output Extracts the comments in the code Organizes the comments Export as markdown Documentation generator #algoliaSearchParty @bobylito
19. Documentation in the static website era > Fully compatible with jsDoc comments > Under active development > Built-in javascript API Documentation.js #algoliaSearchParty @bobylito
20. Documentation in the static website era Metalsmith architecture Read Write #algoliaSearchParty @bobylito
21. Documentation in the static website era Metalsmith plugin Files Files #algoliaSearchParty @bobylito
22. Documentation in the static website era Documentation.js plugin Files Files Extracts JS documentation data Organizes documentation in files #algoliaSearchParty @bobylito
23. Documentation in the static website era Our pipeline Read Write Pug plugin + JSDoc specific mixins Documentation.js plugin #algoliaSearchParty @bobylito
24. Documentation in the static website era > Editorial content with reference doc > Tools you know > Requires some time investment Results #algoliaSearchParty @bobylito
25. Get more from your doc! #AlgoliaSearchParty @bobylito
26. Documentation in the static website era > Edit this page button > Jsdoc is more structured than markup Easy contributions #algoliaSearchParty @bobylito
27. Documentation in the static website era > The API can be separated in concepts > Organizing topics with the learning curve in mind > Driven by the business logic of the doc based on the jsDoc data Topic oriented documentation #algoliaSearchParty @bobylito
28. Documentation in the static website era Runnable example #algoliaSearchParty @bobylito > The user know what they get > They can copy it
29. Documentation in the static website era > Generate usage in pseudo code > Non formal way of seeing the API Usage #algoliaSearchParty @bobylito
30. Documentation in the static website era > Document framework specific concepts? > Add custom tags in the comments > Output them in the generated documentation Extend the semantic #algoliaSearchParty @bobylito
31. Reflexions and future #AlgoliaSearchParty @bobylito
32. Documentation in the static website era > Metalsmith is small and very easy to hack > Maybe other tools could fit too > Other languages could benefit from this approach Current stack #algoliaSearchParty @bobylito
33. Documentation in the static website era > jsDoc is typing without verifications > documentation.js support flow as typing > Double bonus: Writing type once + checks Code semantics #algoliaSearchParty @bobylito
34. Documentation in the static website era > Documentation is key for a successful library > You don’t have to rely on old stacks > Documentation is data, you can harness it Conclusion #algoliaSearchParty @bobylito
35. Thank you Questions? Alexandre Stanislawski Software engineer / Algolia @bobylito bobylito
36. Documentation in the static website era • InstantSearch.js documentation • react-instantsearch documentation Tools • Documentation.js • Metalsmith • jsdoc-to-markdown • jsdoc Some interesting blog post on the doc topic • Making docs more inspiring • In defense of jsDoc #algoliaSearchParty @bobylito Reference