As I see it, modern technical documentation comes in two basic formats: books and help systems. The key differentiator is the reader's expectation about how the documentation is used and not the actual production medium.
Books are intended to be used in a linear, narrative fasion. A user expects to start at one point (a chapter head or section head) and then move forward through the pages to gain more detailed information about the task identified on the start page. A chapter starts off with an overview of ESB processes and then proceeds to provide more granualar information about them. Location has meaning and the content flows together to build a complete picture.
Help systems are intended to be used contextually like a web. A user expects to be dropped into the system at a topic that is relative to the task at hand and then traverse links to any relative information. The idea of chapter and section are meaningless. Location is valueless and each page is a relative island with bridges leading to other islands that may provide further information.
In PDF, and print, the difference between a book and a help system is hard to define except that the help system will almost always feel incomplete and disjointed. PDF, like print, is meant for linear content since it is harder to jump around and the viewers all prominently display location.
In HTML, things are more flexible. HTML books can feel linear and help systems can feel web-like.
HTML books should prominently display their TOC and provide some indication of position in the TOC. They should also provide navigation buttons for traversing the content linearly. Clues like the word chapter and section also help orient the user.
HTML help systems, while most have a TOC system, can dispense with a majority of the location trappings since location has little value. Help systems should not have linear navigation tools, since linear navigation does not always translate into the expected behavior for the user. Words like chapter and section should be expunged since they confuse the user by implying organizational constraints that are not valid in the help system.
Things get confusing for help systems since they often have a TOC panel that displays a linear organization of pages that appear to be grouped into nested structures like chapters and sections. Look at an Eclipse help system's TOC and it is easy to think that it can be used like a book. Start using it that way and you will soon become frustrated because, even if there was a way to navigate linearly, the actual content is not linear in the same sense as a book. Some high-level topic may be a big process that the nested topics provide detailed sub-processes and context, but it is rarely the case that it flows like a book. It is intended so that a user can quickly land on a single page, perhaps by triggering F1 from the UI, and get the information they need. They can choose to explore the provided links to other topics or not. In a book, they would likely need to click through to the pages that follow for more information.
A book is a longer, more descriptive, leisurely way to learn about something. It is intended as a way to deliver content at a deep level in a pedigogical manner. A help system is a collection of quick cards that deliver targeted information so a user can get on with the task at hand. The idea that a writer can create a document that fits both purposes is foolish. The result, like all attempts at making hybrids, will be something that does neither job well.
August 16, 2010
August 13, 2010
Documentation in an Agile World
Most agile frameworks are programmer focused and don't talk about the documentation part of product development. Its not that agile frameworks don't consider documentation an important part of product developement. It's that documentation is a black art to programmers and is often hard to quantify (and we writers like it that way: it allows us to resist change and maintains our sense of creativity).
For example take the following story:
The second question is wheter the story, with the documentation included, could be fit into a single sprint. The documentation cannot really be written until after the implementation is underway and cannot be QAd until after the implementation is complete. The developer will also need to spend some time with the writer providing information. So, should any story with documentaiton impact be split into two stories: one for engineering and one for documentation (the documentation story is dependent on the engineering story)? IMHO splitting stories into a programming story and documentation story is the best way to do it, but it leaves open the possibility that the documentation story will get prioritized out of the release.
Another question that including documentation in agile frameworks that I've heard involves having skin in the game. The concern is that writers, because they cannot write code, may have sprints where they have no active tasks (no skin in the game). In traditional development models, the programmers get started building stuff right off the bat and the writers settle into what they call "disovery mode". The writers are researching what the programmers are building. At some later point in the release cycle, after the programmers have built a bunch of stuff, the writers start writing. So, it makes sense that there is a concern that in early sprints, writers will have no skin in the game. However, I think that this is not going to be a concern in actuality. The writers always have user requests that filter in from previous releases that can be completed in early sprints. They also have areas where they know the documentation can be improved. Given that functionality will start appearing after the first sprint, the writers should have something new to document by sprint number two.
One more question. This one combines concerns from both the previous questions: How do you create acceptence criteria for a story like "understanding the user roles for Apama" or "research the Sonic WS-Security implementation"? My opinion is that you don't because they are not stories they are tasks that need to be completed as part of resolving a story. The task may require an entire sprint, but that does not change the fact that it is just a task. I also don't think that the task will take an entire sprint because such tasks will be constrained tighter than "research WS-Security" to something more along the lines of "research how to secure a Web service using Kerberos tokens." It is possible that some reasearch tasks may take more than a sprint, but programmers may also need to spend a sprint doing research on ways to implement some functionality. The framework has space for it.
For example take the following story:
As a developer implementing an algorithmic trading application, I need to put price constraints in place to ensure that the algorithm operates within safe boundaries.The acceptence criteria is pretty clear "it is done when the developer can add price contraints to his trading algorithm". The functional part of this is easy to measure and understanding what to build is also clear. But what about the documentation part of the story? What is the acceptence criteria? "A procedure that explains how to implement a price constraint." That is not easily verifyable. I could write a procedure that is simple and just walks the developer through the steps:1: add this line of code. 2: include these two parameters in the argument list. etc. Does that really satisfy the requirement such that the developer knows how to implement the price constraint? It is ultimately going to involve some subjectivity.
The second question is wheter the story, with the documentation included, could be fit into a single sprint. The documentation cannot really be written until after the implementation is underway and cannot be QAd until after the implementation is complete. The developer will also need to spend some time with the writer providing information. So, should any story with documentaiton impact be split into two stories: one for engineering and one for documentation (the documentation story is dependent on the engineering story)? IMHO splitting stories into a programming story and documentation story is the best way to do it, but it leaves open the possibility that the documentation story will get prioritized out of the release.
Another question that including documentation in agile frameworks that I've heard involves having skin in the game. The concern is that writers, because they cannot write code, may have sprints where they have no active tasks (no skin in the game). In traditional development models, the programmers get started building stuff right off the bat and the writers settle into what they call "disovery mode". The writers are researching what the programmers are building. At some later point in the release cycle, after the programmers have built a bunch of stuff, the writers start writing. So, it makes sense that there is a concern that in early sprints, writers will have no skin in the game. However, I think that this is not going to be a concern in actuality. The writers always have user requests that filter in from previous releases that can be completed in early sprints. They also have areas where they know the documentation can be improved. Given that functionality will start appearing after the first sprint, the writers should have something new to document by sprint number two.
One more question. This one combines concerns from both the previous questions: How do you create acceptence criteria for a story like "understanding the user roles for Apama" or "research the Sonic WS-Security implementation"? My opinion is that you don't because they are not stories they are tasks that need to be completed as part of resolving a story. The task may require an entire sprint, but that does not change the fact that it is just a task. I also don't think that the task will take an entire sprint because such tasks will be constrained tighter than "research WS-Security" to something more along the lines of "research how to secure a Web service using Kerberos tokens." It is possible that some reasearch tasks may take more than a sprint, but programmers may also need to spend a sprint doing research on ways to implement some functionality. The framework has space for it.
August 11, 2010
What Does Documentation Do?
I'm often asked to explain what value I think documentation provides, what role does it play in making a good product. Most people think of documentation as a neccessary evil or just a bunch of words that are better left unread. Many people's experience with technical documentation, mine included, is frustrating. It never seems to guide on the path to doing the thing you really want to do. It may tell you how to use the "burn and dodge" tool or "use the process designer," but it doesn't really tell me how to selectively darken a portion of a photograph or assemble my services into a process flow.
So what does most documentation do? It explains the features that make up a product. It tells the user how to use the process designer and all of the paths to getting there. It may even mention a few of the reasons a user may want to use the process designer. The problem is that most users don't want to use the process designer. They want to assemble their services into a process flow. More likely the user has an even more specific goal such as assembling my services into a sequntial process flow so that they look like a single service to my customers.
So what should documentation do? It should provide a user the information they need to darken a portion of a photograph. To accomplish their goal, the user will need to use the dodge and burn tool. However, they need to use it in a specific way (only one way) and they are more likely to find the informaiton because it relates to their goals.
Why does documentation often look like feature documentation and not user documentation? One: product release plans are often a list of features and not a list of users stories. Two: writers don't have access to customers to actually understand their goals and needs. Three: the myth that writing user focused documentation is too expensive. Writers can get out of the trap by pushing on product owners to provide user stories and access to customers. Writers can also start pushing back against the myth. It takes a lot of time to fully document the seventeen ways to implement a widget and all the stuff around it. It takes a lot less time to figure out why the user wants to implement that widget and document the best path to accomplishing the goal. It is also a lot more valuable.
So what does most documentation do? It explains the features that make up a product. It tells the user how to use the process designer and all of the paths to getting there. It may even mention a few of the reasons a user may want to use the process designer. The problem is that most users don't want to use the process designer. They want to assemble their services into a process flow. More likely the user has an even more specific goal such as assembling my services into a sequntial process flow so that they look like a single service to my customers.
So what should documentation do? It should provide a user the information they need to darken a portion of a photograph. To accomplish their goal, the user will need to use the dodge and burn tool. However, they need to use it in a specific way (only one way) and they are more likely to find the informaiton because it relates to their goals.
Why does documentation often look like feature documentation and not user documentation? One: product release plans are often a list of features and not a list of users stories. Two: writers don't have access to customers to actually understand their goals and needs. Three: the myth that writing user focused documentation is too expensive. Writers can get out of the trap by pushing on product owners to provide user stories and access to customers. Writers can also start pushing back against the myth. It takes a lot of time to fully document the seventeen ways to implement a widget and all the stuff around it. It takes a lot less time to figure out why the user wants to implement that widget and document the best path to accomplishing the goal. It is also a lot more valuable.
Subscribe to:
Posts (Atom)