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
   

   View Slide

2. 5 MONTHS AGO…
   

   View Slide

3. “DOES THAT WORK WELL
   FOR DOCUMENTATION?”
   

   View Slide

4. 3 MONTHS AGO…
   

   View Slide

5. View Slide

6. INTERVIEWED
   46 PROJECTS
   

   View Slide

7. WANTED TO DISCOVER
   SOMETHING GROUNDBREAKING
   

   View Slide

8. SPOILER ALERT:
   I DIDN’T
   

   View Slide

9. 46 PROJECTS
   

   View Slide

10. 46 PROJECTS
    (all open source)
    

    View Slide

11. ETC
    

    View Slide

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?
    

    View Slide

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?
    

    View Slide

14. WHAT WERE YOU
    USING BEFORE?
    

    View Slide

15. MARKDOWN FILES
    

    View Slide

16. A WIKI
    

    View Slide

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

    View Slide

18. SOMETHING SELF-MADE
    

    View Slide

19. WHAT’S WRONG WITH
    THESE SOLUTIONS?
    

    View Slide

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

    View Slide

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

    View Slide

22. “NOT PRETTY AND NOT
    ORGANIZED”
    

    View Slide

23. WHY DID YOU SWITCH?
    

    View Slide

24. THE USUAL SSG PERKS
    

    View Slide

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

    View Slide

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

    View Slide

27. SMALL TEAMS
    

    View Slide

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

    View Slide

29. LESS HASSLE
    

    View Slide

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

    View Slide

31. BIGGEST SURPRISE
    

    View Slide

32. COMMUNITY
    

    View Slide

33. EASE OF CONTRIBUTING
    

    View Slide

34. BUT ALSO…
    

    View Slide

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

    View Slide

36. WHAT WASN’T IN THEIR
    ANSWERS?
    

    View Slide

37. PROGRAMMING
    LANGUAGE
    

    View Slide

38. WHAT SSG DO YOU USE?

    PROS/CONS?
    

    View Slide

39. SO. MANY. ANSWERS.
    

    View Slide

40. ETC
    

    View Slide

41. docusaurus.io
    

    View Slide

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
    

    View Slide

43. gatsbyjs.org
    

    View Slide

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
    

    View Slide

45. github.com/lord/slate
    

    View Slide

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
    

    View Slide

47. jerkyllrb.com
    

    View Slide

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
    

    View Slide

49. readthedocs.org / sphinx-doc.org
    

    View Slide

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

    View Slide

51. TAKEAWAYS
    

    View Slide

52. USE A VARIETY OF TOOLS
    

    View Slide

53. DOCUMENTING CODE
    VS
    DOCUMENTING TOOLS
    

    View Slide

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

    View Slide

55. HOW LONG DID IT
    TAKE TO MIGRATE?
    

    View Slide

56. View Slide

57. WOULD YOU
    RECOMMEND IT?
    

    View Slide

58. EVERYONE SAID YES
    

    View Slide

59. “WHOLEHEARTEDLY”
    

    View Slide

60. “WITHOUT A DOUBT!”
    

    View Slide

61. BUT…
    

    View Slide

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

    View Slide

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

    View Slide

64. AND BECAUSE IT’S ALL
    OPEN SOURCE…
    

    View Slide

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

    View Slide

66. @carolstran
    

    View Slide