Greetings Everyone,
This weekend I have worked upon documenting by updating the docs at OpenMRS Wiki.
The documentation process can slow down the creative process to the point where you either:
1. Produce design ideas at the pace of development, or
2. Freeze ideas in the form of documents, diagrams, and requirements until they are ready to go later on in the process.
I think this is an oversimplification of documentation, and when, where, and why it’s important to a project.
I live in the land of client services, where every project involves a new set of stakeholders, participants, audience types, and overall business objectives.
Ryan’s team is developing one set of products, used the same way by every customer. There is little customization or need for bureaucratic buy-in as they are their own client, and the strategy may already exist and be a given. However, I see 37signals’ thoughts and propositions on workflow often espoused by design agencies and firms working with client services, and unfortunately I don’t think they overlap well.
While we can all appreciate an expedited process, it is not a system that can support long-term complex client projects.
This tendency to assume documentation is a waste of time—or as Ryan puts it, “I used to think design teams made so many diagrams and documents because… well, they like that sort of thing.”—greatly devalues the importance of clarifying important issues and goals in writing.
It is immature to say that some people just like that sort of thing, when in reality, unless you are an extremely detail-oriented control freak who is trained or gifted as a writer, you probably dread the notion of having to create detailed and important documentation when you’d rather be coding or designing. No, documentation is not something people just do because they like to do it; it is actually important. However, documents and their usefulness should always be held up to scrutiny, and improvements should be made whenever possible.
Just as the design process should seek to create something perfect and useful for the users and the client, so should the documentation. Documentation can be the first set of deliverables within an agency process to become outdated, stale, or redundant—mainly because they are dismissed as unimportant or left to a lackluster team to plod through begrudgingly. This doesn’t need to be the case if we throw out what we think documentation means and seek to find more meaningful ways to integrate the process of documentation.
Recording Creativity
I find myself interviewing designers and developers these days and spending as much time looking at their writing skills as I do their technical and design skills. I place a tremendous amount of value on someone’s appreciation for and ability to conduct strategic thinking. We live in an age where a knee jerk reaction is to “just do it” or find the “app for that” problem.
You can’t replace good old fashioned brainstorming, and the results of that kind of thinking must be successfully documented.
Documents can be exciting, inspiring, and creative forms of expression. Documents can be “living” data, intended to be evolving road maps that can empower a client team long after the vendor has left and the project deliverables have been handed over. Documents are often the foundations that survive the longest and inform the next iteration of thinking. They are building blocks that should inform the future, not create problems or bottlenecks for the present.
Clarification Improves Efficiency
Some of the most important documentation we create for clients is where we restate recommendations or strategic goals. While one may argue that this is a rehashing of a productive group conversation, what many who are not as familiar with management roles may forget is that important people who have some say in the progression of the project may not have been part of these group collaborative conversations.
Often, teams must move strategic goals and recommendations up the pipeline for approval, sign-off, and budget allocations. These stakeholders often don’t have time to sit through the nitty gritty of the conversions and brainstorming exercises, but they do need to see the final documentation.
This paper trail will also serve as reminders to new members of the team who come on board mid-project and need to catch up. It’s a reality that teams will shift, and the last thing you want to have to do is backtrack because a new VP of communications is hired.
Documentation, when done successfully, can keep forward momentum in place and keep the team focused.
Trust is Built on Stability
Additionally, documentation creates trust. We’ve all sat through great meetings only to see good ideas forgotten, see tasks fall to the wayside, and get stuck in those frustrating loops of “well … we talked about this, so I assumed it was going to happen.” Documentation sets expectations, provides clarity, and creates safety nets. It prevents outliers from coming in and playing “dumb” and derailing a project.
It prevents clients from bullying vendors with the old “we talked about this” game.
It prevents vendors from talking a great game but playing “dumb” when it comes to the deliverables. It provides a sense of accountability, and it gives teams something to cross check against.
One of our documents is the Creative Brief. One part of this document is a list of keywords describing the tone and style of the design. This document is formed after meetings and is based on collaborative discussions and fact-finding sessions and research. The list of keywords is short and to the point. However, this list is often referenced during the course of the project by the designers, the developers, and the client. If one of the keywords is “friendly,” we have documentation (approved and signed off on by the client) which empowers us to make certain decisions and have them backed up. It prevents an outlier from coming in mid-project and saying, “This should be more slick-looking” or “Why are all these colorful icons included?” The documentation sets things in stone. It reminds, reinforces, clarifies, and limits the scope of the project. Without documentation, we often find ourselves in never-ending circles. Even the mere act of writing something down gives it more legitimacy.
Documentation Makes Things More Real
We know that writing is a helpful tool for memory, we have learned that lists help keep us organized, we have even seen studies that suggest the act of writing something down ensures it has a higher likelihood of succeeding. Many of us were told by parents to write down pro and con lists before making big decisions. We often can’t see something clearly until it is clearly written out before us. Perhaps the problem with documentation is the tendency toward wasted words and ineffective thinking? I suspect the issue is not with documentation, but with the types of documents being created for the purposes set in place. I also just have to say I find it ironic that someone at 37signals is talking about documentation being a waste of time when their most popular product, Basecamp(which we use and very much like), is essentially an application for better organizing and sharing documentation.
GSoC 2015 with OpenMRS 