a story about engineering repo docs @ linkedin

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