Write With an Agile Mindset
The Agile Manifesto doesn't provide any rigid guidelines for writing documentation in terms of agile principles. However, it suggests a methodology that allows you to write from an agile mindset. The manifesto states that Agilists value:
Individuals and interactions over processes and tools.
Working software over comprehensive documentation.
Customer collaboration over contract negotiation.
Responding to change over following a plan.
Given these values, what documentation should you expect to produce for an agile project?
It’s safe to say that these values are focused on delivering a product and value to the customer. Any time you spend on a project should add value and not waste time on meaningless meetings, activities, pointless features, or tasks that add little to no benefit for the customer. This goes for documentation as well as coding.
Let’s go back to the waterfall styles of project management (Six Sigma, SDLC, etc). In this type of approach, everything comes in phases, and documentation is a separate and predefined phase that takes up a big piece of the total budgeted time for the project. Working from an agile mindset forces you to reconsider such approaches; to re-evaluate what you document to determine if it’s even necessary.
Some people think that with an agile approach, the documentation should only be in the code. This is not the case. There are plenty of necessary elements for an agile project that are not code-related and that provide significant value to the customer.
Documenting with an agile mindset means that you don’t need to plan much of the documentation because you understand that the project can and probably will change as it progresses, and you want your documentation efforts to be able to adapt to those changes. Therefore, practice just-in-time documentation. To avoid wasting time, documentation in an agile project should only happen when it’s necessary.
How do I know when documentation is necessary?
Ah-ha! There’s the big question.
Know When you Need it, and When you Don’t
The idea of just-in-time documentation can be confusing. It doesn’t mean that you don’t consider the future needs of the project, just that you don’t fully plan them at the beginning. Decide what documentation you need to produce. If you have an idea of how the sprints will go, identify which pieces belong to which sprint. It’s important to have a good idea of what documentation you need beforehand, but don’t spend time on it until it's necessary.
Use the following questions to help decide when documentation is needed:
Is the documentation needed now? Since you’re practicing just-in-time planning, you only need to write documentation as it’s needed. If the documentation you’re considering applies to a later sprint, then wait on it. You only need to write documentation that applies to the current sprint.
Who is the target audience? Is it an individual, a department, your client, or a future maintenance team? Knowing this can help you decide if actual documentation is appropriate as opposed to some other means of passing on the communication.
How will the target audience use the documentation? Will they use it as a reference tool? Or maybe a training manual? Identifying the expected use for the documentation will help you decide how critical it really is.
How much it will cost? This is a biggie. Costs can balloon quickly, and that's something you're trying to avoid in an agile project. Identify how much a piece of documentation will cost to produce (money and resources), and then decide if you need it. Is the value greater than the cost? If not, then you should probably toss it out.
In agile documentation, the goal is to produce just-enough documentation. Waterfall processes tend to document absolutely everything, and that’s wasteful. Your goal is to document just what the stakeholders need. That’s where you provide the greatest value for the customer.
Know the What, the When, and the Where of Your Documentation
We’ve been talking about how to decide what project documentation is needed and when to write it. Let’s categorize documentation needs by time. For example:
Needed before the project starts.
Needed during the project.
Needed after project completion.
I know that sounds absurdly simple, but it’s an effective way of focusing your efforts to help facilitate just-in-time documentation.
Remember that unlike waterfall approaches, there is no documentation phase in an agile approach. So a broad categorization based on this simple timeline makes it easy to create a more fluid approach to documenting a project. Project features in an agile project are added incrementally, with changes occurring often. The documentation must, therefore, be written incrementally as well, so it can evolve with the project.
Let’s look a bit closer at these three timelines.
Before the Project
You require very little documentation at the beginning of your project. Remember, you're using just-in-time documentation, so you don't write since the work hasn’t started.
To kick off the project, you just need to document a few key pieces of information:
Two or three high-level architecture diagrams to identify the high-level components of the solution you will implement.
A description of the main characteristics of the proposed product.
A list of primary requirements - these may be high-level or detailed, depending on how well the project has been defined at this point.
You don’t need to provide any design information at this point. However, you should define just-enough information to get the team started. This information will most likely be written in your client brief.
During the Project
While your product is being developed, you will likely produce two types of documentation:
Just-enough requirements - input given to developers for each sprint.
System and business rules implemented - output of each sprint to be shared with stakeholders and later maintenance teams.
The most common way to provide the just-enough requirements for each sprint is to provide a user story. User stories give just-enough information for developers and consist of a description and acceptance criteria. The description takes the following form:
“As <actor> I want to <action> in order to <added value to the customer>.”
The acceptance criteria define the terms of evaluation that exist between the team and the product owner that determine if the story is completed.
Remember that in an agile project, user stories are not exhaustive requirement specifications for a single activity, but instead provide the guidelines on what the developers are expected to implement.
After the Project
Throughout the project, you will have incrementally produced user stories and acceptance results, and your developers have followed best practices in documenting their code in-line, so by the time the product is complete, your current should describe all of the features implemented in the project. In other words, other than project-specific documentation elements that stakeholders might ask for, your documentation is complete.
Now Back to the Where of Your Documentation
Since agile documentation evolves with the project throughout development, the documentation artifacts must be living documents. A living or dynamic document is continually edited and updated. They must, therefore, be kept in an environment that supports living artifacts. This brings us to the where of agile documentation.
Your project’s documentation should be easily accessible and updatable. Using a standard word processing software like MS Word makes it static. In an agile environment, treat your documentation like your source code and use living document platforms like Google Docs or project wikis on GitHub. Other options, including code-based tools like Cucumber, Concordion, FitNesse, SpecFlow, and Pickles, help build your living documentation.
There are many ways to manage your agile documentation. Ultimately, it is up to you to decide on a solution that will work best for you, your team, and your project.
Tips for Writing Exceptionally Clear Documentation
Writing superb technical documentation is a hard task, but reading terrible technical documentation is even worse. Have you ever discovered that you were more confused about a product after reading the manual? It’s painful, right? You don’t want to be the person who inflicts that sort of pain on others, so you want to learn to write superb documentation! Am I right?
To help you write clear and effective documentation, without getting bogged down with a million rules you’ll never remember, I’m borrowing a list of seven rules from an excellent article by Bob Reselman.
Bob’s seven rules are:
Dry sucks.
Before you start, be clear about what you want your reader to do after you end.
Write to a well-formed outline.
Avoid ambiguous pronouns.
Clarity = illustrations + words.
When dealing with concepts... use logical illustrations and examples.
Embrace revision.
Now, what do these rules mean? If you want to read the complete article, please feel free. Bob does an excellent job explaining them. To keep us moving forward through this course, I’ll summarize them.
Dry Sucks
We’ve all fallen victim to the dry technical document. You start reading, and by the time you’re into the second paragraph… well, would you look at that? You never got to the second paragraph. You’re now on your third rendition of the second sentence of paragraph one, and your eyes are getting heavy.
Let’s face it. Boring writing doesn't cut it. The internet has engineered the human race to want constant entertainment and immediate gratification. If your documentation can’t hold your reader’s attention, your reader’s Facebook or Twitter feed will.
There are forces all around you campaigning for your attention at this very moment! Thank goodness this isn’t dull, boring writing or I’d have lost you a long time ago. (That’s assuming you’re still here. If not, then I am ashamed.) Your readers will be in the same position. So, how do you write technical documentation that captures and holds your reader’s attention while still providing what might be some dull, although critical, information?
I mentioned earlier in the text that it was important to use humor cautiously. I also pointed out that I like using humor in my writing. I’m using it rather liberally here, which means I could be violating my own rule, but maybe I’ll get away with it. You’ll know I did if this bit makes it through editing. :D
But seriously, the easiest way I know to keep a reader or students in a classroom entertained is to keep myself entertained. Bob and I have that in common. If I’m not having fun writing something, the reader may get annoyed. If I'm bored, the reader will be bored. If I'm confused, the reader will be confused. If I don't care about what I’m writing, the reader won’t care about reading it.
This first rule is the hardest to follow because there aren’t any rules for following the rules. How do you know if your readers will find your writing entertaining? How do you know your readers aren’t rolling their eyes at your attempts to be funny? (You could be rolling your eyes at me right now.) I can’t tell you how or when to use humor. You need to cultivate your voice. Yes, that’s ambiguous, and this discussion has morphed into a poetry class, but all writing is creative to some degree. So the only advice I can offer you is to have fun. If you enjoy writing your documentation, your reader will be less tempted to browse their social media feed.
Before you Start, Be Clear About What you Want Your Reader to Do After you End
I know exactly what I want you to do after you’re done reading Part 1 of this course. I want you to take the quiz and pass it with flying colors! When you write technical documentation, you expect the reader to take action. In other words, your reader wants to do something, and they expect your document to help.
State your intention at the beginning of the document. Be clear about what you want your reader to do afterward. You can find an illustration of this in every OpenClassrooms course. For example, at the beginning of this course, you can find the following statement:
That’s a pretty clear description what we expect you to be able to do after you finish the course. If you are clear in defining and stating your end objective for the reader, it will make writing the rest of the material much easier.
Write a Well-Formed Outline
The author of the seven rules says, “Writing a technical document without using an outline is like trying to navigate the New York City Subway System without a map. You can end up anywhere and that anywhere may not be where you intended to go.”
You need a way to stay on track, and a well-formed outline can greatly reduce your workload. The key phrase is “well-formed.” All outlines are not created equal. I’ve written poorly-formed outlines and found myself lost in a wombat hole in Australia wondering how in the world I got there.
When you write to a well-formed outline, you know exactly where you've come from, and exactly where you’re going, and unless you’re writing a research paper on marsupials, you won't come across any wombats.
Avoid Ambiguous Pronouns
I’m not a complete grammar fiend, but ambiguous pronouns drive me crazy, and they are all too prevalent in technical writing. Let me give you an example.
Wombats and their ecosystems are important to us at Wombat Rescue. Their care and well-being are central to this project.
Did you spot the ambiguous pronoun? Is the central purpose of the project the care and well-being of wombats, of wombats’ ecosystems, or both? There’s nothing clear about that at all. The care and well-being of wombats are significantly different from the care and well-being of wombats’ ecosystems, so we need to know whose care and well-being we’re trying to help with the project.
If your reader is confused about what you’re trying to say because you use ambiguous pronouns, then you don’t have an effective document.
Clarity = Illustrations + Words
Illustrations, such as graphs, charts, diagrams, or other pictures, should enhance the effectiveness of the document, not detract from it. Your reader doesn’t need to waste his or her time trying to decipher the meaning of the odd graph you dropped in the middle of your document. They need the context of the graph to make sense of it and avoid any confusion, and the easiest way to do this is with a caption.
A best practice is to provide numbered, descriptive captions for all illustrations in your documentation. Provide both elements (a number and a caption), not just one or the other. When you add illustrations, reference them by the figure number and location (above or below the point of reference) in your text.
Finally, if you reference a figure in your text, be sure it matches the number. You don’t want to tell a user to refer to Figure 3 below when the only figure below is Figure 5. Accuracy in writing is a wonderful thing.
When Dealing With Concepts... Logical Illustrations and Examples
If you write about abstract concepts, try to substantiate them with an appropriate illustration and an example to make them easier to understand. Creating such illustrations and examples can be difficult, but they can also make your documentation more clear.
Embrace Revision
"Technical writing is 10% composition and 90% revision!"
~ Thomas Edison
This is the last of Bob’s rules. Documentation rarely comes out perfect with the first draft. Of course, since we’re talking about agile documentation, you already know the first draft is never the only draft. Embracing revision is right at the core of agile methodology. So don’t worry about getting everything right the first time around. Write just-enough so that the documentation does its job for the current sprint or phase, knowing that another revision is on the horizon.
Let’s Recap!
In this chapter, you learned a lot more about agile methodologies and how they can be used in writing technical documentation, specifically:
An Agilist’s goal is always to produce just-enough documentation. This means documenting just what the stakeholders need, no more and no less.
You give the customer the greatest value by not wasting time and resources on producing unnecessary artifacts.
Agile documents are living documents, meaning they are constantly updated as they evolve with the project.
Living documents are like source code, and require living environments. GitHub is a great place to start.
Effective documentation provides value to the reader when it:
Does not bore the reader.
Is clear about what the reader should do after reading.
Is written to a well-formed outline.
Avoids ambiguous pronouns.
Uses illustration coupled with examples for clarity.
Is easily revised.
The next chapter is all about briefs - what they are, why you need them, how they’re used, how they fit within agile methodologies, and why they are a much better alternative to software requirements specifications (SRS) documents.
