Apr 15, 2018 by Wendy Writing

Schoolhouse Docs! How our Tech Writing Process Works

Like most things at MailChimp, the process of making a Knowledge Base (KB) article is … well, a process. Depending on what we’re writing about, it can take a few weeks or a few months. We plan, execute, and write alongside the Development team while new features are built in continuous deployment cycles.  

 

 

From concept to KB article, here’s how our documentation process usually works.

 


 

When MailChimp’s Development team plans a new feature, we lay the groundwork of our documentation strategy.

  • Technical content writers attend development planning meetings and offer early feedback on wording and feature naming. We agonize over things like “canceled” versus “cancelled.” Seriously.
  • Our writers develop an education plan for the feature. They think about the audience’s experience level, the feature difficulty level, and how the concepts fit into MailChimp as a whole.

 


 

Most new features need 1–5 new KB articles, and each article starts as a draft.

  • When a feature is ready to be tested, a writer tries it out and drafts a rough version of a KB article in Google Docs.
  • The writer works with our videographer to capture all necessary images, still shots, and GIFs.
  • The writer checks the technical accuracy of their content. Our colleagues in development, support, research, and quality assurance (QA) help us iron out the details.

 


 

Once an article is drafted, it goes through an intensive review process.

  • The article writer will do a peer review with another writer. They’ll pass the draft back and forth for a few rounds of edits and refinements. (Here are some things we check for during peer reviews.)
  • The peer reviewer ensures the article fits our MailChimp style guide and is readable for most audiences. They’ll also reference our internal technical content style guide to keep terminology consistent and clear.

 


 

After an article is written, reviewed, and edited, it’s time to send it out into the world at product release time.

  • The writer puts the finished draft into our content management system (CMS), inserts images, and adds alt-text for accessibility.
  • The writer checks the content one last time. OK, maybe two last times.
  • They hit publish and the article goes live!
  • Our internationalization expert adapts the article for French and Spanish speakers.
  • The writer spreads the word about the new article among other departments in the company via newsletter and slack announcements. They also make sure the KB link is added to the MailChimp app in helpful places.

 


 

And that’s it, right? Nope! Publishing is just the beginning. Next, it’s time to listen hard and change fast. (Which happens to be our company motto.)

  • After publishing, we continue iterating on the article to make sure it provides the most accurate information.
  • We collect feedback from MailChimp users and cross-department collaborators and refine, refine, refine as needed. Colleagues share their feedback in person, on slack, or through JIRA tickets. 
  • We also monitor stats. We watch our internal analytics dashboard for article performance over time, and we share the results with the development team.

 


Our docs are constantly evolving, and so is our process.

Is your company’s product documentation process similar to ours, or completely different? Or is there a particular part of our process that you’d like to learn more about in a future post?  

Let us know in the comments!

Discussion

Comment