WriteTheDocs was billed as a “a two-day conference for technical writers, documentarians, and all those who write the docs.” Put on by those behind ReadTheDocs, a project to host, manage, and organize documentation (mostly API docs) for the open source community

While technical writers were certainly in attendance, people who work the help desk/support and developers made up the rest of the attendees. The talks were just as varied, consisting of everything from software, methods, and best-practices of documenting your code, to typography and psycho-social meanings of words, poetry, and business communications. For an infonerd like myself, it was a very enjoyable experience.

Conference Themes

During the two-day conference, several take-home themes became apparent. The first was that documentation is vitally important to the success of your product. It is often the first interaction your customer (or potential customer) has with your product, even before diving into the code. Therefore, well-written, relevant documentation should be rolled into the product development cycle, complete with version control and bug reports (“bad documentation is a bug!”).

Along these lines, even if your product was not intended to be customer facing (an internal tool or methods), internal documentation is better than relying on the “tribal knowledge” of only a few (or one!) employees who know how to use it. Additionally, should your internal tool suddenly be open to the outside world, good docs allow a smoother transition than starting from nothing. Opening speaker, Kenneth Reitz, suggests writing your code and docs as if they are intended to be open source from the start.

A third theme that piqued my interest was the notion that good documentation helps one create a better product. Whether we’re talking about customer interaction or designing a new feature, the very act of writing documentation helps you focus on the problem your code is meant to solve.

Applying Lessons to the Agency Model

Here at Emerge, our product is the service to our clients. Much of what was discussed at the conference on product documentation does not directly apply. However, there are still very good ideas that can easily be applied to the agency model, especially in the case of internal documentation. Feature specifications have to capture both the needs and wants of the client, and provide instructions for how it should function upon completion.

Applying the lessons mentioned above, we can approach a client’s specific problem with docs first. These docs would detail the problem explicitly and provide the solution specs before a line of code is ever written. The documentation could then feasibly be passed to any developer to complete the task. These same docs can be used during QA to determine if the software created is actually solving the problem presented, and with minimal editing, could even become the tutorial/guide for how the client is to use the software.

WriteTheDocs was a conference unlike any other I’ve attended. It brought a complete focus to the varied yet related fields of documentation that are typically couched as one or two talks at a traditional tech conference. While the conference could do with some minor improvements (more break out sessions, chat/discussion time, maybe a couple tracks), I look forward to seeing how it develops and hope to attend next year.