a story about engineering repo docs @ linkedin

15
A Story About Engineering Repo Docs @

Upload: greg-mcmillan

Post on 12-Apr-2017

25 views

Category:

Internet


8 download

TRANSCRIPT

Page 1: A Story About Engineering Repo Docs @ LinkedIn

A Story About Engineering Repo Docs @

Page 2: A Story About Engineering Repo Docs @ LinkedIn
Page 3: A Story About Engineering Repo Docs @ LinkedIn

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

Page 4: A Story About Engineering Repo Docs @ LinkedIn

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

Page 5: A Story About Engineering Repo Docs @ LinkedIn

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

Page 6: A Story About Engineering Repo Docs @ LinkedIn

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

Page 7: A Story About Engineering Repo Docs @ LinkedIn

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

Page 8: A Story About Engineering Repo Docs @ LinkedIn

Treat Docs Like Code

Ship it!Code Tests Docs+ + =

Page 9: A Story About Engineering Repo Docs @ LinkedIn

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

Page 10: A Story About Engineering Repo Docs @ LinkedIn
Page 11: A Story About Engineering Repo Docs @ LinkedIn

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

Page 12: A Story About Engineering Repo Docs @ LinkedIn

Authoring Tools Exploration

Sphinx Markdown Review Board YUIdoc Javadoc JSdoc Gitbook Rest.li (autogen'd APIs)

Page 13: A Story About Engineering Repo Docs @ LinkedIn

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 …

Page 14: A Story About Engineering Repo Docs @ LinkedIn

We’re Hiring

Come talk to us …

Page 15: A Story About Engineering Repo Docs @ LinkedIn

Demo