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!

8c5989329a85b590fecdb4f7a97cbe3a?s=128

Carolyn Stransky

June 25, 2018
Tweet

Transcript

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

    @carolstran
  2. 5 MONTHS AGO…

  3. “DOES THAT WORK WELL FOR DOCUMENTATION?”

  4. 3 MONTHS AGO…

  5. None
  6. INTERVIEWED 46 PROJECTS

  7. WANTED TO DISCOVER SOMETHING GROUNDBREAKING

  8. SPOILER ALERT: I DIDN’T

  9. 46 PROJECTS

  10. 46 PROJECTS (all open source)

  11. ETC

  12. 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?
  13. 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?
  14. WHAT WERE YOU USING BEFORE?

  15. MARKDOWN FILES

  16. A WIKI

  17. “A WIKI AND CUSTOM PAGES WITH LOOSE TEXTS AND HTML

    FILES”
  18. SOMETHING SELF-MADE

  19. WHAT’S WRONG WITH THESE SOLUTIONS?

  20. “PROBLEMS KEEPING DOCS ONLINE IN SYNC WITH THE CODE IN

    SYNC WITH THE PAGES…”
  21. “WIKIS ARE VERY DIFFICULT TO KEEP UP TO DATE”

  22. “NOT PRETTY AND NOT ORGANIZED”

  23. WHY DID YOU SWITCH?

  24. THE USUAL SSG PERKS

  25. “WE GAINED IN HAVING A STRUCTURED HIERARCHY, VERSION CONTROLLED DOCS

    THAT MATCHED THE SOFTWARE”
  26. “AN EXTENSIBLE PLATFORM FOR OUR DOCUMENTATION THAT WE CAN NOW

    USE IN MULTIPLE PLACES”
  27. SMALL TEAMS

  28. “WE ARE A SMALL TEAM AND DOCUMENTATION MAINTENANCE TAKES TOO

    MUCH TIME, SO WE LOOKED INTO AUTOMATION”
  29. LESS HASSLE

  30. “I DIDN’T HAVE TO DEAL WITH COMMON PROBLEMS FOR WEBSITES

    (SEO, OPTIMIZATIONS, ETC)”
  31. BIGGEST SURPRISE

  32. COMMUNITY

  33. EASE OF CONTRIBUTING

  34. BUT ALSO…

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

  36. WHAT WASN’T IN THEIR ANSWERS?

  37. PROGRAMMING LANGUAGE

  38. WHAT SSG DO YOU USE?
 PROS/CONS?

  39. SO. MANY. ANSWERS.

  40. ETC

  41. docusaurus.io

  42. “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
  43. gatsbyjs.org

  44. “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
  45. github.com/lord/slate

  46. “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
  47. jerkyllrb.com

  48. “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
  49. readthedocs.org / sphinx-doc.org

  50. “STRUCTURED HIERARCHY AND HOSTING. HANDS DOWN.” PROS “MUCH BIGGER LEARNING

    CURVE THAN WE HAD EXPECTED” CONS
  51. TAKEAWAYS

  52. USE A VARIETY OF TOOLS

  53. DOCUMENTING CODE VS DOCUMENTING TOOLS

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

  55. HOW LONG DID IT TAKE TO MIGRATE?

  56. None
  57. WOULD YOU RECOMMEND IT?

  58. EVERYONE SAID YES

  59. “WHOLEHEARTEDLY”

  60. “WITHOUT A DOUBT!”

  61. BUT…

  62. “DEPENDS ON WHAT YOU’RE TRYING TO ACHIEVE, I WOULD RECOMMEND

    IT WITH CAVEATS”
  63. “…IT MAY TAKE SOME TIME TO GET USED TO, BUT

    IT’S WORTH IT IN THE END”
  64. AND BECAUSE IT’S ALL OPEN SOURCE…

  65. “SINCE OUR SETUP IS OPEN SOURCE, YOU CAN BENEFIT FROM

    THE WORK WE ALREADY PUT IN THAT SETUP”
  66. @carolstran