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!

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…
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?
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