A Story About Engineering Repo Docs @
Our Target Audience
• Internal eng docs • For 3,000 engineers working @ LinkedIn • Write code and debug it all day long at scale • No external facing customer docs • No books • No hardcopy • No PDFs • Searchable bite size topics, how tos, code samples
Wiki Growing Pains
• Engineering has used a wiki for 10+ years • Primary knowledge base • 150,000+ wiki pages • Adding 3,000+ new pages each month • 1.5 million saved versions of those pages • 50% of content not updated 2 > years
Wiki Archiving
• We expire and archive 2,000 wiki pages each month • Archiving Plugin for Confluence • See also “12 Enterprise Deployment Tips” at midori-global.com
Major Content Drift
source code <—> docs out of sync
• A growing negative perception trend in Engineering towards wiki • Can’t trust the wiki for critical types of low-level developer docs • Examples: APIs, frontend frameworks, libraries
Open Eng Docs System
3,000 engineers
5 tech writers
• Empower engineers to write their own docs • Use their own workflow and code management system • Leverage familiar technologies: Git, Markdown, Python, Review Board, Gradle • Anyone can write the docs (not only tech writers) • Not a closed system for tech writers only (FrameMaker, XML, XMetal, …)
600:1 ratio
Treat Docs Like Code
Ship it!Code Tests Docs+ + =
Authoring Workflow
App’s Git repo
Multiproduct wrapper
Sphinx docsgit add
mint product creategenerate-skeletonsphinx-build -b html
git commitgit-review creategit-review dcommit -r 828453
git push
Source code Review BoardProduct
DashboardWeb Server
Internal Eng Writing in the WTF Zone
1. Create a Git repo 2. Create a multiproduct 3. Generate a default skeleton 4. Download Sphinx and its dependencies 5. Write the docs 6. Preview the HTML locally 7. Git push to the server
Exciting but scary Content life cycle insanity < 6 months Merge conflict butterflies. Tell the delete your code story. Work in your own separate ‘docs’ dir whenever possible
Authoring Tools Exploration
Sphinx Markdown Review Board YUIdoc Javadoc JSdoc Gitbook Rest.li (autogen'd APIs)
Next Up…
• LaTex equations support in Sphinx • Autogen’d docs from source code • Retool web server for 3000+ Git repos • Templates for getting started • Improve search • Ongoing research: JSDoc, YUIDoc, Javadoc • Testing, testing, testing …
We’re Hiring
Come talk to us …
Demo