Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Generating docs in the static website era

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