A LOOK INTO STATIC SITE GENERATORS
FOR OPEN SOURCE DOCS
@carolstran
Slide 2
Slide 2 text
5 MONTHS AGO…
Slide 3
Slide 3 text
“DOES THAT WORK WELL
FOR DOCUMENTATION?”
Slide 4
Slide 4 text
3 MONTHS AGO…
Slide 5
Slide 5 text
No content
Slide 6
Slide 6 text
INTERVIEWED
46 PROJECTS
Slide 7
Slide 7 text
WANTED TO DISCOVER
SOMETHING GROUNDBREAKING
Slide 8
Slide 8 text
SPOILER ALERT:
I DIDN’T
Slide 9
Slide 9 text
46 PROJECTS
Slide 10
Slide 10 text
46 PROJECTS
(all open source)
Slide 11
Slide 11 text
ETC
Slide 12
Slide 12 text
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?
Slide 13
Slide 13 text
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?
Slide 14
Slide 14 text
WHAT WERE YOU
USING BEFORE?
Slide 15
Slide 15 text
MARKDOWN FILES
Slide 16
Slide 16 text
A WIKI
Slide 17
Slide 17 text
“A WIKI AND CUSTOM PAGES WITH
LOOSE TEXTS AND HTML FILES”
Slide 18
Slide 18 text
SOMETHING SELF-MADE
Slide 19
Slide 19 text
WHAT’S WRONG WITH
THESE SOLUTIONS?
Slide 20
Slide 20 text
“PROBLEMS KEEPING DOCS ONLINE
IN SYNC WITH THE CODE IN SYNC
WITH THE PAGES…”
Slide 21
Slide 21 text
“WIKIS ARE VERY DIFFICULT TO
KEEP UP TO DATE”
Slide 22
Slide 22 text
“NOT PRETTY AND NOT
ORGANIZED”
Slide 23
Slide 23 text
WHY DID YOU SWITCH?
Slide 24
Slide 24 text
THE USUAL SSG PERKS
Slide 25
Slide 25 text
“WE GAINED IN HAVING A STRUCTURED
HIERARCHY, VERSION CONTROLLED
DOCS THAT MATCHED THE SOFTWARE”
Slide 26
Slide 26 text
“AN EXTENSIBLE PLATFORM FOR
OUR DOCUMENTATION THAT WE CAN
NOW USE IN MULTIPLE PLACES”
Slide 27
Slide 27 text
SMALL TEAMS
Slide 28
Slide 28 text
“WE ARE A SMALL TEAM AND
DOCUMENTATION MAINTENANCE
TAKES TOO MUCH TIME, SO WE
LOOKED INTO AUTOMATION”
Slide 29
Slide 29 text
LESS HASSLE
Slide 30
Slide 30 text
“I DIDN’T HAVE TO DEAL WITH
COMMON PROBLEMS FOR WEBSITES
(SEO, OPTIMIZATIONS, ETC)”
Slide 31
Slide 31 text
BIGGEST SURPRISE
Slide 32
Slide 32 text
COMMUNITY
Slide 33
Slide 33 text
EASE OF CONTRIBUTING
Slide 34
Slide 34 text
BUT ALSO…
Slide 35
Slide 35 text
“THERE’S A BIG COMMUNITY TO
CHOOSE VARIOUS TOOLS FROM”
Slide 36
Slide 36 text
WHAT WASN’T IN THEIR
ANSWERS?
Slide 37
Slide 37 text
PROGRAMMING
LANGUAGE
Slide 38
Slide 38 text
WHAT SSG DO YOU USE?
PROS/CONS?
Slide 39
Slide 39 text
SO. MANY. ANSWERS.
Slide 40
Slide 40 text
ETC
Slide 41
Slide 41 text
docusaurus.io
Slide 42
Slide 42 text
“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
Slide 43
Slide 43 text
gatsbyjs.org
Slide 44
Slide 44 text
“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
Slide 45
Slide 45 text
github.com/lord/slate
Slide 46
Slide 46 text
“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
Slide 47
Slide 47 text
jerkyllrb.com
Slide 48
Slide 48 text
“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
Slide 49
Slide 49 text
readthedocs.org / sphinx-doc.org
Slide 50
Slide 50 text
“STRUCTURED HIERARCHY AND
HOSTING. HANDS DOWN.”
PROS
“MUCH BIGGER LEARNING CURVE THAN
WE HAD EXPECTED”
CONS
Slide 51
Slide 51 text
TAKEAWAYS
Slide 52
Slide 52 text
USE A VARIETY OF TOOLS
Slide 53
Slide 53 text
DOCUMENTING CODE
VS
DOCUMENTING TOOLS
Slide 54
Slide 54 text
THERE’S A DIFFERENCE
BETWEEN API DOCS AND
EVERYTHING ELSE
Slide 55
Slide 55 text
HOW LONG DID IT
TAKE TO MIGRATE?
Slide 56
Slide 56 text
No content
Slide 57
Slide 57 text
WOULD YOU
RECOMMEND IT?
Slide 58
Slide 58 text
EVERYONE SAID YES
Slide 59
Slide 59 text
“WHOLEHEARTEDLY”
Slide 60
Slide 60 text
“WITHOUT A DOUBT!”
Slide 61
Slide 61 text
BUT…
Slide 62
Slide 62 text
“DEPENDS ON WHAT YOU’RE
TRYING TO ACHIEVE, I WOULD
RECOMMEND IT WITH CAVEATS”
Slide 63
Slide 63 text
“…IT MAY TAKE SOME TIME
TO GET USED TO, BUT IT’S
WORTH IT IN THE END”
Slide 64
Slide 64 text
AND BECAUSE IT’S ALL
OPEN SOURCE…
Slide 65
Slide 65 text
“SINCE OUR SETUP IS OPEN SOURCE,
YOU CAN BENEFIT FROM THE WORK
WE ALREADY PUT IN THAT SETUP”