Tag Archives: Twitter

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

I’m at Write the Docs today in Portland 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 Twitter on documentation projects. About 9 months ago Twitter acquired a software training company Marko and Simeon both worked at. The goal was to create Twitter University for internal training and learning. It didn’t take long, though, for someone to suggest they tackle the technical documentation as well.

The technical documentation they work on at Twitter is internal-facing. It’s engineer-to-engineer documentation and not the public API specs. They ran a survey about the internal docs. Using the net promoter score standard they found that most people hated the internal docs. Some common complaints were that the docs were incomplete, deprecated, non-existant, or unclear.

Their technical docs team was just 3 doc writers. They view the team as the engineering grease internal to the company. The goal is to make things run smoother. To do this they’re making docs like code. The process they’re working toward is to code, test, doc, and then ship.

They’re taking lessons from the test-driven-development shift to bring docs in to that process. Developers at Twitter have gotten accustomed to needing tests finished before they commit code. The challenge is to make that cultural assumption the same around docs.

The plan is three-pronged. The platform is DocBird, the publishing platform. Above that lie self-service tools and templates. Finally there’s DocDay, an internal doc sprint that aims to promote documentation internally. As they got started they realized there was no coherent plan or standard to docs. Different teams used different tools, formats, and processes. Some teams were even using Google Docs. Their internal wiki has more than 60,000 pages across more than 150 spaces.

In treating their docs as code they’re checking the docs in to git, those docs are plain text, and they’re regularly reviewed and merged. This is where technology comes in to the rescue. They built a homebrew documentation platform they call DocBird. They hit a few roadblocks in this process. The fact that DocBird is not a wiki, isn’t ReStructuredText, and isn’t generated from the source code were all initial 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 template layer of their project is aimed to enabling developers to get to minimum viable documentation as fast as possible. They’re working to enforce consistency in documentation through those same templates; things like a similar language are important here. It solves the problem discussed in an earlier talk about how intimidating a blank page is. By filling some default language in to the template they help developers get over that initial hurdle.

In terms of coverage the goal is to have 100% of known projects covered with the same docs. They’re bootstrapping this by starting 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 people using resources well is key. They’re pushing education as a way to leverage those three documentarians to have maximum impact. By working on templates, for example, 3 documentarians can influence hundreds of docs. Ultimately better technology alone will not create a culture of documentation.

The key problem is getting Twitter’s thousand+ engineers to write docs. On the one hand they’re telling the engineers that a lack of docs should be considered technical debt. On the other, though, they’re telling the engineers that if they want other teams to adopt their library they need to package it attractively; docs are a key part of that package.

Developer to Documentarian. A neat post from Write the Docs co-organizer Troy Howard. In it he covers the four things that make a documentarian distinct from a developer or technical writer.

What If Social Networks Just Aren’t Profitable?

What if we designed a social network to be small, self-supporting, and independent from the outset? How would it look, work, and feel? I bet it would come out looking nothing like the ones we’ve got now, the ones still trying to turn water into gold.

I set up a quick status blog on WordPress.com today. It auto posts the content to Twitter so it’s handy for when I want to post the occasional status. Plus, I’m now dogfooding another part of what I work on every day which is always good.

Effectively Instapaper has found a way to keep its users engaged with the site’s main purpose, reading, while offering users ways of keeping tabs other readers. It’s like getting a peek at someone else’s bookcase, without them knowing that you peeked.

Imagine what would happen if Twitter operated this way: you have no inkling of who is following you and others have no clue if you are following them. You just have an account that you post to, occasionally a person responds to you. The only way you know if a person is following you is when you go to Direct Message them.

Imagine that, because what would really change?

Ben Brooks – The Masked Social Network.

Referral traffic to this site over the past week. Matt beats Twitter. :)

Missing the point with school social networks

I read an Edudemic article this morning about the future of school social networks:

Now, a movement is afoot to create student-friendly social networking sites, which would be limited to education and bound to particular districts or schools. These sites would give students the chance to communicate with peers in person and via the computer, in a setting not unlike an online school. Yet the most desirable aspect of school-friendly social networks may be that they would allow students to work together in a productive manner, while providing adults with the peace of mind sites like Facebook simply cannot offer.

This is all well-intentioned but it likely won’t be successful in any meaningful way.

It reminds me of educational video games. Things that education executives draw up to try to marry technology with their version of learning. They don’t work. You can’t create a video game that kids will want to play by removing its soul.

Similarly, creating a school social network by allowing for social connections which parents, teachers, and administrators approve of misses the point. You’re leaving out the soul of a network. It’s this soul that makes Facebook and Twitter so appealing in the first place.

Growing up outside of a very small, rural town meant being extremely isolated in many ways. Had you told a junior high or high school version of myself that I could use something like Twitter, Facebook, or, hell, even my blog to connect through shared interests with people irrespective of place, age, or social status I would have been floored.

That’s the soul of these platforms. That’s what makes them revolutionary for schooling. If you think creating sanitized, school-friendly networks watched over by parents and administrators is going to create any meaningful learning opportunities then you’re totally missing the point.

Educate kids on proper usage. Teach them online safety. Show them the power of serendipitous connections to people a world away. But don’t, for their own sake, limit their potential because of fear.