When your team is remote, distributed, highly collaborative, and fast-paced, having solid documentation is core to effectiveness. Before we were the Storytelling Studio, our teams who did this kind of work developed a system for building documentation into our culture, and we’ll continue iterating on this process as we charge ahead.
Having documentation about all facets of our work keeps us accountable, efficient, and makes onboarding much easier — both for the members of our ever-growing Storytelling Studio, and for members of other teams who interact with our process for the first time.
This is a peek into how we make documentation work for us, and can maybe serve as a framework as you build out your own documentation culture.
Keep a queue of unanswered questions
We keep a running list of questions in an incoming queue in Trello, pictured below. You can use any tool, though — a spreadsheet, a Google Doc. We encourage everyone to add to it regularly. The “To document” column represents a running list of questions or ideas that the teams stumble upon during the course of projects, sprints, meetings, conversation in person and in Slack, and, most commonly, onboarding new team members. New team members add questions to the board as part of the onboarding process, as they stumble upon things that our docs didn’t answer for them.
Know the types of things you want to document
It’s easy for technologists and designers to think about documentation in terms of commented code, Github wikis, or style guides. Those are all incredibly important, but what we’re talking about is much bigger than the work itself. We’re also talking about documenting how you get things done.
Some examples of what lives in our docs:
- Mission: What is the high-level vision we’re working toward, and the quarterly objectives to get us there?
- Working on projects: How do you initiate them? What questions do you ask from the start? What tools should be used to track work, and what are the best practices and expectations for using those tools?
- Evaluation: How do you prioritize your work? What’s your rubric? Without a clear sense of how you prioritize, it can seem arbitrary to your stakeholders, and easy for your team to make exceptions that set you off course from your goals.
- Communication: How to communicate with stakeholders, be it editors or a product team or sales, in a way that is consistent, easily accessible, and honest. What’s your practice when your team messes up or something breaks? How do you solicit feedback on designs? (I touch on this in the next section). How do you let people know what kind of work is upcoming, and what’s been accomplished?
- Technical: How to set up your engineering workstation, and get started with projects.
- User-facing: How do you use our tools? How do you request something from our team? How do you check the status of projects we’re working on?
- Design and research: What are the best practices for researching, for conducting interviews, for doing design reviews, for using typefaces and making logos?
Plan the Documentation Day
Once your queue of “To document” cards has built up in Trello (about ~30 cards is the sweet spot on a team the size of Storytelling Studio), it’s probably an indicator that it’s time for another Documentation Day.
- Assess the incoming queue to see if everything’s still relevant, and what’s missing. When doing this, also take a pass at your existing docs to see what needs updating.
- Pick a day to dedicate to documentation. Do a poll with the team to see what date works, then immediately block off the whole day in a calendar invite.
- Pick a location. We like using Breather for offsite space in NY, and General Assembly for offsite classroom space in DC. You can also book a meeting room in your office or go to a good coffee shop.
- Schedule an hour in the days before your Documentation Day for the group to assess what’s in the queue, find what’s missing, assign cards, and prioritize so you can hit the ground running on your Documentation Day.
- Plan a lunch or dinner for the day-of. Please be considerate of dietary preferences.
- Think about having a good template set up (like this example) so folks have a framework for how to write.
- Also write your guiding principles for what makes good documentation. We can publish ours at some point, but we touch on themes such as the voice of our writing and how to be platform agnostic (not brand-specific).
- We also love starting a collaborative Spotify playlist for our distributed teammates to jam to the same music.
Getting started during Doc Day
Take another pass at Trello: At the start of the day, everyone on the team should review their assignments and adjust if needed.
Weigh in on cards others are writing: If we see cards that others are working on and have ideas for a specific theme they should touch on or questions they should answer, we leave a comment with suggestions.
After writing, move the card to a “Peer Review” column: After we’ve written a document, we move it to the peer review column, include links in the description, and share the document with everyone.
Review peers’ docs: We keep an eye on the peer review-column and add ourselves to various docs. If no one has signed up to peer review, we drop doc links in the Slack room. When you've started reviewing, use the "Reviewing" column.
After two people have peer-reviewed: After it’s been peer-reviewed by two people, we move it to the “Reviewed, ready for Starter Kit” column. A facilitator takes a final pass at everything and adds it to a centralized location. For us, that’s an internal Chorus site that houses all our documents. For you, it could be an internal wiki or even a Google doc that serves as an index of all other Google Docs.
Getting focused
In general, it can be very easy to lallygag through a Documentation Day. We encourage our folks to churn through it. Turn on your music, plug in your headphones, switch to Slack’s Do Not Disturb mode, and just get words down on paper. Even if you don’t know exactly the best way to write something, just get bullet points down or questions to answer and a peer-reviewer can help you brainstorm.
Following up
There will always be a few loose ends to tie up after Documentation Day. In the days following, managers or facilitators should encourage team members to set aside some time on their calendars to finish up what remains. Someone else should also be responsible for adding all links to a centralized place or updating relevant links. Also take time to distribute relevant docs to other teams or stakeholders as needed.
Other ways to build this into your culture
We build this into our culture by having a formal process and setting aside time every few months to do the work of writing documentation. There are many other ways a team could make this happen with the pace of their own work. Today at SRCCON — a conference about newsroom code, culture, and process — we are facilitating a workshop on other ways to build documentation into team culture. We’ll update this post with the best ideas that come from that session.
