Recommended
More Related Content
Similar to Generating docs in the static website era
Similar to Generating docs in the static website era (20)
Recently uploaded
Recently uploaded (20)
Generating docs in the static website era
- 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
- 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
- 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