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:
- It lowers the barrier of entry to product usage.
- It decreases the reliance on subject-matter experts, allowing everyone to get up to speed efficiently.
- 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.
- 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.
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.