Write the Docs: Simeon Franklin & Marko Gargenta — TechDocs at Twitter: Creating the Culture of Documentation

I’m at Write the Docs today in Port­land and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Marko and Simeon both work at Twit­ter on doc­u­men­ta­tion projects. About 9 months ago Twit­ter acquired a soft­ware train­ing com­pany Marko and Simeon both worked at. The goal was to cre­ate Twit­ter Uni­ver­sity for inter­nal train­ing and learn­ing. It didn’t take long, though, for some­one to sug­gest they tackle the tech­ni­cal doc­u­men­ta­tion as well.

The tech­ni­cal doc­u­men­ta­tion they work on at Twit­ter is internal-facing. It’s engineer-to-engineer doc­u­men­ta­tion and not the pub­lic API specs. They ran a sur­vey about the inter­nal docs. Using the net pro­moter score stan­dard they found that most peo­ple hated the inter­nal docs. Some com­mon com­plaints were that the docs were incom­plete, dep­re­cated, non-existant, or unclear.

Their tech­ni­cal docs team was just 3 doc writ­ers. They view the team as the engi­neer­ing grease inter­nal to the com­pany. The goal is to make things run smoother. To do this they’re mak­ing docs like code. The process they’re work­ing toward is to code, test, doc, and then ship.

They’re tak­ing lessons from the test-driven-development shift to bring docs in to that process. Devel­op­ers at Twit­ter have got­ten accus­tomed to need­ing tests fin­ished before they com­mit code. The chal­lenge is to make that cul­tural assump­tion the same around docs.

The plan is three-pronged. The plat­form is DocBird, the pub­lish­ing plat­form. Above that lie self-service tools and tem­plates. Finally there’s Doc­Day, an inter­nal doc sprint that aims to pro­mote doc­u­men­ta­tion inter­nally. As they got started they real­ized there was no coher­ent plan or stan­dard to docs. Dif­fer­ent teams used dif­fer­ent tools, for­mats, and processes. Some teams were even using Google Docs. Their inter­nal wiki has more than 60,000 pages across more than 150 spaces.

In treat­ing their docs as code they’re check­ing the docs in to git, those docs are plain text, and they’re reg­u­larly reviewed and merged. This is where tech­nol­ogy comes in to the res­cue. They built a home­brew doc­u­men­ta­tion plat­form they call DocBird. They hit a few road­blocks in this process. The fact that DocBird is not a wiki, isn’t ReStruc­tured­Text, and isn’t gen­er­ated from the source code were all ini­tial problems.

Since the docs live in the code repo they’re able to track the amount docs drift away from code. The goal is to keep things in sync, but it’s a challenge.

The tem­plate layer of their project is aimed to enabling devel­op­ers to get to min­i­mum viable doc­u­men­ta­tion as fast as pos­si­ble. They’re work­ing to enforce con­sis­tency in doc­u­men­ta­tion through those same tem­plates; things like a sim­i­lar lan­guage are impor­tant here. It solves the prob­lem dis­cussed in an ear­lier talk about how intim­i­dat­ing a blank page is. By fill­ing some default lan­guage in to the tem­plate they help devel­op­ers get over that ini­tial hurdle.

In terms of cov­er­age the goal is to have 100% of known projects cov­ered with the same docs. They’re boot­strap­ping this by start­ing with readme files that point to all the docs that exist. They don’t all have to be in DocBird right away.

With only 3 peo­ple using resources well is key. They’re push­ing edu­ca­tion as a way to lever­age those three doc­u­men­tar­i­ans to have max­i­mum impact. By work­ing on tem­plates, for exam­ple, 3 doc­u­men­tar­i­ans can influ­ence hun­dreds of docs. Ulti­mately bet­ter tech­nol­ogy alone will not cre­ate a cul­ture of documentation.

The key prob­lem is get­ting Twitter’s thou­sand+ engi­neers to write docs. On the one hand they’re telling the engi­neers that a lack of docs should be con­sid­ered tech­ni­cal debt. On the other, though, they’re telling the engi­neers that if they want other teams to adopt their library they need to pack­age it attrac­tively; docs are a key part of that package.

What If Social Net­works Just Aren’t Profitable?

What if we designed a social net­work to be small, self-supporting, and inde­pen­dent from the out­set? How would it look, work, and feel? I bet it would come out look­ing noth­ing like the ones we’ve got now, the ones still try­ing to turn water into gold.


I set up a quick sta­tus blog on WordPress.com today. It auto posts the con­tent to Twit­ter so it’s handy for when I want to post the occa­sional sta­tus. Plus, I’m now dog­food­ing another part of what I work on every day which is always good.

The Masked Social Network

Effec­tively Instapa­per has found a way to keep its users engaged with the site’s main pur­pose, read­ing, while offer­ing users ways of keep­ing tabs other read­ers. It’s like get­ting a peek at some­one else’s book­case, with­out them know­ing that you peeked.

Imag­ine what would hap­pen if Twit­ter oper­ated this way: you have no inkling of who is fol­low­ing you and oth­ers have no clue if you are fol­low­ing them. You just have an account that you post to, occa­sion­ally a per­son responds to you. The only way you know if a per­son is fol­low­ing you is when you go to Direct Mes­sage them.

Imag­ine that, because what would really change?

Ben Brooks — The Masked Social Net­work.

Missing the point with school social networks

I read an Edu­demic arti­cle this morn­ing about the future of school social net­works:

Now, a move­ment is afoot to cre­ate student-friendly social net­work­ing sites, which would be lim­ited to edu­ca­tion and bound to par­tic­u­lar dis­tricts or schools. These sites would give stu­dents the chance to com­mu­ni­cate with peers in per­son and via the com­puter, in a set­ting not unlike an online school. Yet the most desir­able aspect of school-friendly social net­works may be that they would allow stu­dents to work together in a pro­duc­tive man­ner, while pro­vid­ing adults with the peace of mind sites like Face­book sim­ply can­not offer.

This is all well-intentioned but it likely won’t be suc­cess­ful in any mean­ing­ful way.

It reminds me of edu­ca­tional video games. Things that edu­ca­tion exec­u­tives draw up to try to marry tech­nol­ogy with their ver­sion of learn­ing. They don’t work. You can’t cre­ate a video game that kids will want to play by remov­ing its soul.

Sim­i­larly, cre­at­ing a school social net­work by allow­ing for social con­nec­tions which par­ents, teach­ers, and admin­is­tra­tors approve of misses the point. You’re leav­ing out the soul of a net­work. It’s this soul that makes Face­book and Twit­ter so appeal­ing in the first place.

Grow­ing up out­side of a very small, rural town meant being extremely iso­lated in many ways. Had you told a junior high or high school ver­sion of myself that I could use some­thing like Twit­ter, Face­book, or, hell, even my blog to con­nect through shared inter­ests with peo­ple irre­spec­tive of place, age, or social sta­tus I would have been floored.

That’s the soul of these plat­forms. That’s what makes them rev­o­lu­tion­ary for school­ing. If you think cre­at­ing san­i­tized, school-friendly net­works watched over by par­ents and admin­is­tra­tors is going to cre­ate any mean­ing­ful learn­ing oppor­tu­ni­ties then you’re totally miss­ing the point.

Edu­cate kids on proper usage. Teach them online safety. Show them the power of serendip­i­tous con­nec­tions to peo­ple a world away. But don’t, for their own sake, limit their poten­tial because of fear.