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. 5.
  2. 11.

    ETC

  3. 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?
  4. 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?
  5. 16.
  6. 28.

    “WE ARE A SMALL TEAM AND DOCUMENTATION MAINTENANCE TAKES TOO

    MUCH TIME, SO WE LOOKED INTO AUTOMATION”
  7. 32.
  8. 40.

    ETC

  9. 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
  10. 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
  11. 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
  12. 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
  13. 51.
  14. 56.
  15. 61.
  16. 63.

    “…IT MAY TAKE SOME TIME TO GET USED TO, BUT

    IT’S WORTH IT IN THE END”
  17. 65.

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

    THE WORK WE ALREADY PUT IN THAT SETUP”