Documentation Days

What is "Doc Day"?

Doc Day is the opportunity for a team to take a break from their day to day routine to write crucial or necessary documentation.

Abstract

"Efficiency is doing things right; effectiveness is doing the right things." - Peter Drucker

The purpose of Doc Day is to provide an opportunity for a team (or department) to take a break from their day to day routine and to either gather and organize documents, write new documentation, update or archive old documents, or to tackle long overdue documentation tasks.

The most common problem technical writers face is huge documentation backlogs and regular requests from both users and the teams to create or maintain documentation. While some roles of a technical writer is to become a subject matter expert, often time it is very difficult given time constraints, shifting schedule deadlines, and the consumer/tech writer ratio (at one point, I worked for a company that had a ratio of 2400 to 3).

While there are many methods to complete day to day documentation tasks, bigger projects and opportunities for the company to be more efficient can linger on and on and sometimes sit too long on the back-burner. Consider this scenario: John needs to write a document about a widget. John searches the company's internal documentation system for two looking information he needs. For the most part, he may find fragments here and there but not enough to go on. At this point, John resorts to information from his notes from previous team meetings (another hour spent researching). John knows that Adam (an engineer on the project) mentioned a point about the widget. John meets with Adam to gather information about the widget over the course of an hour only to discover that he wrote the tests for the widget and his information is too low level for the documentation. He informs John that Mary was the primary engineer assigned to develop the widget. Both John and Adam meet with Mary to get detailed information about how the widget was designed to work (or not). After a brief introduction to the task at hand, Mary invites yet another engineer (Po) to this meeting. Mary then explains to three different people the overview and main features with both Adam and Po asking questions and getting into minor debates every so often over the course of an hour. If Mary would have been given the time to write an overview document explaining the purpose of the widget, listed the features, and current bugs, she could have saved John five hours, Adam two hours, and Mary and Po one hour of searching, discussing, and meeting. Total time spent researching and sharing: 9 hours. Time Mary could have written the overview: 1 hour.

In this scenario, we see a rather bad use of time for everyone involved (though I'm not going to knock the value of personal interactions or connections). Engaging in a regularly scheduled document event, the engineers can spend an entire day writing new guides or refreshing documentation and possibly archive outdated documents that the team, their manager, and their consumers deem worthy of the Doc Day. The technical writer acts as a facilitator during this event providing support (both technical and writing related), hosts meetings prior to the event discussing the goals and assignments, writing and sharing templates with the team, and making oneself available throughout the event for answering any issues that arise. At the end of the day, the Doc Day concludes with a meeting where the participating members of the event meet, share their documents and snippets of their documents with the team, enjoy some refreshments, and (optional) receive an merit of honor (small gift or token of esteem). The participating members would each vote on the presentation, completeness of the documentation assigned, and any other criteria set by the event.

In my experience, everyone who ever participated in a Doc Day event, planned their time around the event to dedicate themselves solely to documentation, generally enjoyed the time while writing, looked forward to the next Doc Day event, and was thankful for everyone sharing their documentation effort at the end of the day. The team then reviewed the documents to learn more about what was written and applied any nuggets of knowledge to their own respective projects. The technical writer and the writer's manager is happy because some of their backlog and/or feature requests have been resolved.

How Does It Work?

The lead of a team designates a day (blessed from management) to work purely on documentation for one day. The team is given a notice of at least a week in advance so that they can submit topics to be documented.

Team members submit a list of items that can be documented in less than a day to their lead. The lead then goes through the list and makes the final list of topics to be written. Topics may be assigned to the submitted or to someone else who has deeper knowledge of the proposed topic. Topics should be able to be completed in less than one working day (approximately 7 man hours). Team members may write more than one topic if the topics can be completed by the end of the day.

Frequency

Ideally, Doc Days should occur every quarter but at the very least, once a year per team.

What Do We Write?

Anything that should be documented but currently isn't. Here are a few examples:

• A procedure that needs documentation
• Missing documentation from API modules
• Cross-training documents
• Instructional guides on various technologies
• Revising outdated documentation
• Anything that can be beneficial to the team, company-at-large, or our customers

The documentation can be either internal or externally facing.

Support

You friendly neighborhood tech writer is more than happy to help out with any writing issues you may encounter during your Doc Day assignment. Spell-check, grammar correction, technical issues with Confluence (wiki), and image capture/manipulation are a few services your tech writer is happy to assist you with. If English isn't your first language (or even if it is) and you're working on a document that will be public facing, please have someone review it before publishing it.

Doc Day Event

Prior to the Doc Day, the technical writer will set up a wiki page with all the assigned topics, writers, and links to the pages to be documented. This page will then be shared with the team the day before the Doc Day.

The day before the Doc Day, the team meets to go over their assignment topics and answer any and all questions about the Doc Day. The technical writer should be present to assist in answering any questions.

On the day of the event:

1. Team members start their day by reviewing their writing assignment(s).
2. Team members write their assigned topic(s).
3. Once a topic has been written, it can be submitted to the tech writer or team lead for review.
4. At the end of the day, the team meets for an hour to review the completed documents and vote on the best presentation and topic. The writer with the most votes wins a super cool prize.
   1. The doc review may or may not include snacks and liquid refreshments (of the adult beverage type).
   2. The prize can be anything: a badge of honor, gift card to Amazon (something of monetary value), or a trophy that is passed along from time to time.