Why documentation matters

Good documentation = more inclusion

The DNC Tech Team builds the data products and technological infrastructure that powers Democratic campaigns up and down the ballot.

An essential part of this infrastructure is good documentation. When done correctly, it is a tool for inclusion.

The role of good documentation

What do we mean by “documentation”? Documentation is the written material that accompanies a product (whether that is data, a tool, a model, etc.). It provides the information needed to properly use the product.

Comprehensive and accessible documentation achieves three things:

1. It lowers the barrier of entry to product usage.
2. It decreases the reliance on subject-matter experts, allowing everyone to get up to speed efficiently.
3. It empowers people to use products independently.

Within the political ecosystem, documentation and the democratization it allows is particularly important because turnover rates are high (particularly after each election cycle), and the pool of people with experience using the products that power campaigns can be limited.

Without good documentation, teams run the risk of excluding capable and interested candidates who are new to the political ecosystem, narrowing an already limited pool of talent.

In the last year, we’ve placed a focus on developing comprehensive user-facing documentation for our products. It has been a team effort, and one that is ongoing.

Four tenets of documentation

Identify the primary user

Our user base is broad. Users range in organization (presidential campaigns to state parties to sister committees), function, type of program, and experience level.

Similar to creating a product, when developing documentation, we start with two questions:

• What is the problem we are trying to solve?
• Who are we solving it for?

Often, a product serves a wide range of use cases and experience levels. In those situations, we aim to create documentation that is accessible to users with the least experience, while highlighting the range of use cases the product can be applied to.

Written for the next election cycle

Turnover is natural within all industries. Documentation creates institutional memory that allows people to navigate products without relying on experienced (former) colleagues.

To ensure that future staffers can easily use our products, we keep both quantity and quality of documentation in mind.

We create documentation for all of the tools, data, and products we develop. This includes metadata (descriptions about a data field) for every new field in Phoenix, our data warehouse.

Meet users where they are

Tips for creating easy-to-understand documentation:

• Explain the “why”: Provide contextual information about why the product is valuable. Highlight how it can help the user.
• Avoid jargon: Documentation should be written in a way that doesn’t require the user to look up any terminology. A good starting place is to avoid acronyms and abbreviations.
• Make it referenceable: Documentation plays dual roles as a manual and a reference point. Highlight the most important points in documentation to make it easy for someone to quickly digest the key information.

We include a TL;DR section at the top of documentation to make it easily referenceable.

• Include examples: Examples help show how a product works and/or how it should be used. This has been particularly useful for explaining data science concepts like the National Record Linkage algorithm.
• Use visuals: Visuals illustrate information — in many cases, better than words can.

Example graphic included in DNC Data Science documentation by Sarah James

Make it actionable & engaging

Documentation should make it as easy as possible for a user to go from learning about a product to using it.

To do so, we incorporate example workflows and SQL code into our data and tool documentation. Users are able to see example situations where the product is helpful, then immediately try it out.

Similarly, we’ve recently been testing a new form of documentation: Data Studio and Tableau Dashboards. For data science products, like the 2020 Democratic Party Support Model — which predicts the likelihood that someone will support Democrats, we created a dashboard that allows a user to explore the key inputs to the model in their state, turnout targeting charts, and demographic breakdowns.

Inclusion through information

Creating and maintaining comprehensive, accessible, and engaging documentation takes work. At DNC Tech, it is a cross-team effort. However it is an essential component of, not a supplement to, the products we offer.

A lack of previous experience shouldn’t be a barrier to entry to the political ecosystem. By investing in good documentation, we strive to make it easier for people who are new to the political ecosystem to hit the ground running.

If you’re interested in making a difference in this election cycle and those to come, join our team.