Tag Archives: Twitter

A simpler Twitter

A long time ago I used Craig Mod’s Twitter for Minimalists. It was nice. Using that in a Fluid.app instance gave me the benefits of Twitter’s web application without the distraction of having it in my primary browser.

Craig’s recent tweet about modifying the notifications panel put it back in my mind.

I find the Twitter website to include some key pieces that third-party apps lack. I enjoy seeing favorites and other activity that’s only available through the web interface. The downside is that I dislike the habit of opening it in my primary browser; I prefer distractions that take more deliberate action to open. So I threw together some basic styles and now have this running:

a-simpler-twitter

It helps me build a small, digital habit field around using Twitter. If you want to set up something similar here’s a Gist of the CSS I’m using. Using that in Fluid.app will require the paid version, but it’s just $4.99. I also found this handy replacement icon that looks nice in my dock.

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.