Alexandre Stanislawski
Generating docs in the
static website era
Software engineer / Algolia
Public
@bobylito
bobylito
Slide 2
Slide 2 text
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
Slide 3
Slide 3 text
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
Slide 4
Slide 4 text
#AlgoliaSearchParty
@bobylito
And now a little story
Slide 5
Slide 5 text
Documentation in the static website era
2015: InstantSearch.js v1
#algoliaSearchParty
@bobylito
Slide 6
Slide 6 text
Documentation in the static website era
Jekyll was cool
#algoliaSearchParty
@bobylito
Slide 7
Slide 7 text
Documentation in the static website era
JsDoc less so
#algoliaSearchParty
@bobylito
Slide 8
Slide 8 text
> the tool
> the annotations in the code
jsDoc: 1 word, two things
#algoliaSearchParty
@bobylito
Documentation in the static website era
Slide 9
Slide 9 text
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
Slide 10
Slide 10 text
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
Slide 11
Slide 11 text
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
Slide 12
Slide 12 text
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
Slide 13
Slide 13 text
Documentation in the static website era
#algoliaSearchParty
@bobylito
Not the only one!
Slide 14
Slide 14 text
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
Slide 15
Slide 15 text
#AlgoliaSearchParty
@bobylito
Slide 16
Slide 16 text
Let’s fast forward to
now
#AlgoliaSearchParty
@bobylito
Slide 17
Slide 17 text
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
Slide 18
Slide 18 text
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
Slide 19
Slide 19 text
Documentation in the static website era
> Fully compatible with jsDoc comments
> Under active development
> Built-in javascript API
Documentation.js
#algoliaSearchParty
@bobylito
Slide 20
Slide 20 text
Documentation in the static website era
Metalsmith architecture
Read Write
#algoliaSearchParty
@bobylito
Slide 21
Slide 21 text
Documentation in the static website era
Metalsmith plugin
Files Files
#algoliaSearchParty
@bobylito
Slide 22
Slide 22 text
Documentation in the static website era
Documentation.js plugin
Files Files
Extracts JS
documentation
data
Organizes
documentation
in files
#algoliaSearchParty
@bobylito
Slide 23
Slide 23 text
Documentation in the static website era
Our pipeline
Read Write
Pug plugin +
JSDoc specific mixins
Documentation.js
plugin
#algoliaSearchParty
@bobylito
Slide 24
Slide 24 text
Documentation in the static website era
> Editorial content with reference doc
> Tools you know
> Requires some time investment
Results
#algoliaSearchParty
@bobylito
Slide 25
Slide 25 text
Get more from your
doc!
#AlgoliaSearchParty
@bobylito
Slide 26
Slide 26 text
Documentation in the static website era
> Edit this page button
> Jsdoc is more structured than markup
Easy contributions
#algoliaSearchParty
@bobylito
Slide 27
Slide 27 text
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
Slide 28
Slide 28 text
Documentation in the static website era
Runnable example
#algoliaSearchParty
@bobylito
> The user know what they get
> They can copy it
Slide 29
Slide 29 text
Documentation in the static website era
> Generate usage in pseudo code
> Non formal way of seeing the API
Usage
#algoliaSearchParty
@bobylito
Slide 30
Slide 30 text
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
Slide 31
Slide 31 text
Reflexions and future
#AlgoliaSearchParty
@bobylito
Slide 32
Slide 32 text
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
Slide 33
Slide 33 text
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
Slide 34
Slide 34 text
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
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