Internal docs for startups at Write the Docs NA 2016

This week I’m attending Write the Docs NA 2016. I’m at a session titled “Move Fast And Document Things: Hard-Won Lessons in Building Documentation Culture in Startups”, by Ruthie Bendor.

Ruthie Bendor‘s session was about strategies for writing internal docs at fast-moving organisations. Ruthie is one of the brave engineers who attended a conference full of tech writers!

Internal tech docs are things like README files and wiki pages, containing instructions for setting up engineering environments, and so on. They’re what we write for our colleagues to enable us to build upon our work. Even our future selves will find this documentation useful.

When you work at a technical startup, saying “that’s not my job” doesn’t work.

Ruthie told us a few stories of how she’d experienced internal docs as a software engineer. A telling example was when Ruthie worked at an agency. In that organisation, most of the programs Ruthie wrote weren’t meant for production – they were demos for customers, to be thrown away after they’d met their purpose. In this case, there was no need to write much documentation. This is in contrast to working on production code and procedures, where docs help the company progress.

Another story was about Ruthie’s first few days at a startup, where there was no internal documentation to help her get started with all the tools and processes. She stumbled through the first tasks of getting code committed, repeatedly having to bother other people when she messed up the code base.

Based on her experiences, Ruthie suggests four steps to writing internal documentation for a fast-moving organisation.

  • Figure out what’s broken. Don’t guess. Find out what the rest of the organisation thinks is broken, rather than going on your own assumptions. You’re probably wrong! Find out whether the team values tech documentation, and if not, why not. Possible reasons why engineers may not value docs are the belief that internal docs get outdated too quickly, or that all engineers have the same technical background.
  • Figure out why your organisation cares about fixing its internal technical docs. You may think the docs will make the software last as long as possible, or will help onboard new staff. But these points don’t apply to fast-moving startups. Startups are focused on making the product. Ruthie learned that the people in her organisation value learning from each other. This is why they care about internal docs. What you document and how you document is an expression of your company culture.
  • Couch your solutions in the organisation’s values. Ruthie says this is hacking in the best sense: how to get the results you want with the tools you have, and not necessarily in the traditional way. Think about videos, weekly show and tells, etc.
  • Iterate. At every inflection point of the organisation, reevaluate the values, rinse, repeat.

Incidental learning from this session: The “bus factor” is the number of people who can be unexpectedly lost by a project before the project collapses. It’s the number of people who can be hit by a bus without the organisation going out of business.

Thanks Ruthie! This was a fun and informative session.

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 25 May 2016, in technical writing, Write the Docs and tagged . Bookmark the permalink. 1 Comment.

  1. Thank you for excellent writing tip.
    Australian Essay

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: