Showing posts with label questions. Show all posts
Showing posts with label questions. Show all posts

Friday, March 21, 2014

Agile Documentation

And this, class, is what we call BLASPHEMIES!!!
One of the most common myths I get to dispel as an Agile Coach is that Agile teams don't document. After all, they value Working Software, not Comprehensive Documentation. I have to remind them that the Manifesto states "over" instead of "not", and that true Agilists still see the value in documentation inasmuch as it enhances the working software being developed. These conversations have helped me refine my message over time to the four questions I believe should be asked before documentation is produced.

Who are you documenting for?
Set permissions to 'write-only'
Who is going to read this document that you're going to write? Dean Leffingwell once told me that Agile means avoiding "write-only" documentation. If it's not going to be read, why write it?

Understanding your audience also impacts how you write your documentation. Speak to the level and with the verbiage which which your consumer is most comfortable. This is similar logic to why we include the user in the standard User Story format.

How will you communicate your documentation?
Documentation is not one-size-fits-all. There are hundreds of ways to document, from wikis to man files to interactive wizards. What format are you going to use to publish your documentation?

Another interpretation of this is where will you put the documentation for your consumers to pull? Most documentation is living, not static, so mediums like email are usually very bad. Do you have a team site, knowledge repository, or some other digital location that your consumers can bookmark to find the latest and greatest? Is the location easy to find and "on the main path", or do they have to dig for it? Make your life easy by making your documentation easy to consume.

What will be done with your documentation?
This is more a corollary for the first two questions. For example, you may think you know who you're documenting for, but what if all they do is file the information away and never look at it? Your audience may not be who you think it is - indeed, your audience may not exist at all.

As for the second question, building a README file to document your smartphone game won't be useful, regardless of how well you know your customer or how accessible you make said file - an in-game tutorial will be much better received.

Bottom line: don't start documenting until you know what your consumers' intended purpose is for the documentation.

Can it be automated?
The first three questions speak more to the elimination or simplification of the documentation you produce. By the time you get to this question, you've determined that the documentation is necessary for your end-user, future maintenance team, or whomever to do what they need with your software. So can this documentation be automated?

Documentation for future development and maintenance is often quite simple to automate. You can use certain comment formatting to generate Javadoc or Sandcastle documentation for Java and .NET applications, respectively. You can use tools to generate your class and sequence diagrams as part of each build. There are several forms of technical documentation that can almost always be automated.

User-facing automation is trickier, but not impossible. For instance, you could generate LaTeX templates that are plugged in with data that's auto-fed to it and output documentation in the format that works best for your users. Get creative with it and see what you can come up with.

Questions?
Those are the questions I've developed over time; what are yours? How do you determine what to document and how? Do you find yourself documenting more or less using Agile than Waterfall? How has the nature of documentation changed? I'd love to learn from your experiences.

Wednesday, January 29, 2014

Introspective: Follow-up to Kaizen Questions

I recently wrote a blog post about Asking Kaizen Questions. I saw an example of what may be considered Kaizen Questions on our KAT Board the other day. Let me explain.

We have a large glass board furnished with neon dry erase markers on one of our hallway walls. I don't know what it's official name is, but I call it the KAT Board because it is periodically erased and seeded with one or more questions from our CIO, Karenann Terrell (or KAT for short). Here's the question she posed earlier this month:

"What do you hope to accomplish in 2014?" -- KAT
Once the question is posed, everyone is encouraged to grab markers and write their responses. The other day I walked by and saw this:

"Excellence always. If not excellence, what? If not excellence now, when?"
I saw that and thought, "What excellent examples of Kaizen questions!" They provided a challenge to the status quo and some sense of urgency. I liked it, but I thought it was missing something. I'll come back to that.

Over the past week, I've seen varying levels of engagement at the personal, team, and domain levels, particularly with regard to Agile. As thrilling and exciting as it is to see someone pick Agile up and own it, it is equally frustrating to see someone wait for the organization to transform around them before they decide to act. To take it a step further, it is necessary for each person within a company to own the company's success. If they don't feel that they have a voice or don't see the importance of using that voice, they will eventually outlive their usefulness. Companies with engaged and empowered associates will pass up those whose employees are just there to take orders and get a paycheck.

So I went back to the board and added another question to help deepen both the sense of urgency and personal accountability.

"If not us, who?"

Thursday, January 23, 2014

Asking Kaizen Questions

If you've read my previous material you already know that I'm a big proponent of questioning everything - getting to the "Why?" of what we do. What I've realized lately is that simply asking "Why?", though a good start, is not as effective as asking the right "Why?".

We get better by asking questions and acting on the answers. The better the questions, the better the answers. I'm going to refer to the right kind of "Why?" question as Kaizen questions (full disclosure: I don't know if this is already a thing or not, but a basic Google search tells me it's at least not widely used).

Let me give you an example. One question I get a lot from those resistant to Agile is, "Why should I give up Waterfall?" or "Waterfall's always worked for me; why should I stop?" A slightly more open-minded derivative to this question is, "Why should I try Agile?" If we were to take the Kaizen approach and recognize that perfection is unattainable but improvement is always possible, we would ask, "Why should I continue using Waterfall?" or "What other approaches could I use to deliver quality and value to my customers?"

The Kaizen Question doesn't ask how well the current approach is working because there is an inherent understanding that it could be better. It focuses only on the alternatives to what is currently being done. This type of question is crucial for those adopting Agile to ask themselves as they transition. Otherwise, they risk simply moving from a poor status quo to a better status quo.

If you move to Scrum because you asked yourself, "Why should I try Scrum?" then you are more likely to stick with Scrum and never try something new than if you'd started your journey by asking, "Why should I stick with what I'm currently using?" Do you see the distinction?

I would hope that those who try Scrum eventually adopt a Kaizen mindset and continue to evolve regardless of what question originally got them there. Unfortunately, I have seen too many teams move to Scrum, settle in, and fight against later suggestions of Kanban, DevOps, and other emerging practices and processes. The way I see it, any status quo is a bad status quo and should, therefore, always be challenged. What do you think?