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

A Look Into SSGs for Open Source Documentation

A Look Into SSGs for Open Source Documentation

For the past couple of months, I’ve interviewed nearly 50 open source projects about how they use static site generators for their documentation. And let’s just say that the results were not what I was expecting. Think of this presentation as more of an informal research sharing among fellow static site enthusiasts.

Presented at Static Sites Berlin Meetup
Recording coming soon!

Carolyn Stransky

June 25, 2018
Tweet

More Decks by Carolyn Stransky

Other Decks in Technology

Transcript

  1. A LOOK INTO STATIC SITE GENERATORS
    FOR OPEN SOURCE DOCS
    @carolstran

    View full-size slide

  2. 5 MONTHS AGO…

    View full-size slide

  3. “DOES THAT WORK WELL
    FOR DOCUMENTATION?”

    View full-size slide

  4. 3 MONTHS AGO…

    View full-size slide

  5. INTERVIEWED
    46 PROJECTS

    View full-size slide

  6. WANTED TO DISCOVER
    SOMETHING GROUNDBREAKING

    View full-size slide

  7. SPOILER ALERT:
    I DIDN’T

    View full-size slide

  8. 46 PROJECTS
    (all open source)

    View full-size slide

  9. WHAT SSG DO YOU USE? 

    PROS/CONS?
    WHAT WERE YOU USING BEFORE?
    WHY DID YOU SWITCH?


    HOW LONG DID IT TAKE TO MIGRATE?


    WOULD YOU RECOMMEND IT?

    View full-size slide

  10. WHAT WERE YOU USING BEFORE?
    WHY DID YOU SWITCH?


    WHAT SSG DO YOU USE? 

    PROS/CONS?


    HOW LONG DID IT TAKE TO MIGRATE?


    WOULD YOU RECOMMEND IT?

    View full-size slide

  11. WHAT WERE YOU
    USING BEFORE?

    View full-size slide

  12. MARKDOWN FILES

    View full-size slide

  13. “A WIKI AND CUSTOM PAGES WITH
    LOOSE TEXTS AND HTML FILES”

    View full-size slide

  14. SOMETHING SELF-MADE

    View full-size slide

  15. WHAT’S WRONG WITH
    THESE SOLUTIONS?

    View full-size slide

  16. “PROBLEMS KEEPING DOCS ONLINE
    IN SYNC WITH THE CODE IN SYNC
    WITH THE PAGES…”

    View full-size slide

  17. “WIKIS ARE VERY DIFFICULT TO
    KEEP UP TO DATE”

    View full-size slide

  18. “NOT PRETTY AND NOT
    ORGANIZED”

    View full-size slide

  19. WHY DID YOU SWITCH?

    View full-size slide

  20. THE USUAL SSG PERKS

    View full-size slide

  21. “WE GAINED IN HAVING A STRUCTURED
    HIERARCHY, VERSION CONTROLLED
    DOCS THAT MATCHED THE SOFTWARE”

    View full-size slide

  22. “AN EXTENSIBLE PLATFORM FOR
    OUR DOCUMENTATION THAT WE CAN
    NOW USE IN MULTIPLE PLACES”

    View full-size slide

  23. “WE ARE A SMALL TEAM AND
    DOCUMENTATION MAINTENANCE
    TAKES TOO MUCH TIME, SO WE
    LOOKED INTO AUTOMATION”

    View full-size slide

  24. “I DIDN’T HAVE TO DEAL WITH
    COMMON PROBLEMS FOR WEBSITES
    (SEO, OPTIMIZATIONS, ETC)”

    View full-size slide

  25. BIGGEST SURPRISE

    View full-size slide

  26. EASE OF CONTRIBUTING

    View full-size slide

  27. “THERE’S A BIG COMMUNITY TO
    CHOOSE VARIOUS TOOLS FROM”

    View full-size slide

  28. WHAT WASN’T IN THEIR
    ANSWERS?

    View full-size slide

  29. PROGRAMMING
    LANGUAGE

    View full-size slide

  30. WHAT SSG DO YOU USE?

    PROS/CONS?

    View full-size slide

  31. SO. MANY. ANSWERS.

    View full-size slide

  32. docusaurus.io

    View full-size slide

  33. “GENERATES ALMOST THE THEORETICAL MINIMUM AMOUNT
    OF CODE AND REQUESTS… NOT THROUGH OVER-
    ENGINEERING BUT JUST AS A RESULT OF ITS SIMPLICITY”
    PROS
    DISTINCT THEMING
    AND STYLE
    CONS

    View full-size slide

  34. gatsbyjs.org

    View full-size slide

  35. “IF YOU’RE A REACT DEV, YES. IF YOU WANT
    TO GET INVOLVE WITH GRAPHQL, YES…”
    PROS
    “IF YOU WANT REALLY SUPER SIMPLE
    SOLUTIONS, NO.”
    CONS

    View full-size slide

  36. github.com/lord/slate

    View full-size slide

  37. “I LIKED HOW I COULD INTEGRATE CODE
    EXAMPLES AND THE ONE PAGE DOCUMENT
    MAKES THINGS A LOT MORE SEARCHABLE”
    PROS
    “IT DOES THE JOB,
    AND THAT’S REALLY IT”
    CONS

    View full-size slide

  38. jerkyllrb.com

    View full-size slide

  39. “INTEGRATED MANAGEMENT, REASONABLY
    CUSTOMIZABLE… EASY TO PUSH CHANGES AS
    PART OF MY RELEASE PROCESS.”
    PROS
    “THE BIG ONE IS THE COGNITIVE OVERHEAD
    INVOLVED. ALSO YAML IS UGLY”
    CONS

    View full-size slide

  40. readthedocs.org / sphinx-doc.org

    View full-size slide

  41. “STRUCTURED HIERARCHY AND
    HOSTING. HANDS DOWN.”
    PROS
    “MUCH BIGGER LEARNING CURVE THAN
    WE HAD EXPECTED”
    CONS

    View full-size slide

  42. USE A VARIETY OF TOOLS

    View full-size slide

  43. DOCUMENTING CODE
    VS
    DOCUMENTING TOOLS

    View full-size slide

  44. THERE’S A DIFFERENCE
    BETWEEN API DOCS AND
    EVERYTHING ELSE

    View full-size slide

  45. HOW LONG DID IT
    TAKE TO MIGRATE?

    View full-size slide

  46. WOULD YOU
    RECOMMEND IT?

    View full-size slide

  47. EVERYONE SAID YES

    View full-size slide

  48. “WHOLEHEARTEDLY”

    View full-size slide

  49. “WITHOUT A DOUBT!”

    View full-size slide

  50. “DEPENDS ON WHAT YOU’RE
    TRYING TO ACHIEVE, I WOULD
    RECOMMEND IT WITH CAVEATS”

    View full-size slide

  51. “…IT MAY TAKE SOME TIME
    TO GET USED TO, BUT IT’S
    WORTH IT IN THE END”

    View full-size slide

  52. AND BECAUSE IT’S ALL
    OPEN SOURCE…

    View full-size slide

  53. “SINCE OUR SETUP IS OPEN SOURCE,
    YOU CAN BENEFIT FROM THE WORK
    WE ALREADY PUT IN THAT SETUP”

    View full-size slide