Tag Archives: Top to bottom documentation

Learning Agile – Post #1


Starting from today I am planing to learn Agile while questioning its utility against my last 3 years of experience.

What Agile looks like for most of us?

agile[ ATTRIBUTE: Please check: http://www.flickr.com/photos/78832226@N00/2119855534 to find out how to attribute this image ]

This image is a good description i’d say. I can’t really point why but usually it has something to do with stickers and a whiteboard. I would guess that this is the non IT version and that IT does not have to follow it. It does not make sense to track a piece of work in 2 places.

A story starts with a quick background to set up the scene

“In February 2001 seventeen software developers met at a ski resort in Snowbird, Utah to do some skiing while spending time reflecting on what defined the core principles of agile software development methods.”

2001. Now we are in 2014. Maybe we can improve a bit. The customers have improved a lot. The technology has changed drastically. Here is a random post with multiple images I have found over the internet.

In the same phrase, right after, we are presented the owners of the idea. The software developers. Now, I did a bit of development and I must admit that while doing it I am not quite focused on either customer or business satisfaction. I want the things done is such a way that I can be proud of them while respecting a deadline.

So far, my conclusion is that there might be room for improvement.

Let’s go to the core concepts

This should help me scratch the surface a bit.

“Individuals and interactions over processes and tools
Working software over comprehensive documentation
Customer collaboration over contract negotiation
Responding to change over following a plan”


“Individuals and interactions over processes and tools”

I do not agree entirely, here is why:

1 developer (Dev) costs ~50-250 Euros per hour. 1 product owner (PO) 100-150 Euros per hour. I think this is the minimum “team” necessary for the team word to exist and for agile to happen. Anything less than this and it is called singularity.

A developer starts working (actually writing new code) in at least 30 minutes based on complexity. He needs to find the focus, understand the previous code, create a local branch, read a row of specification.

If during the peak of his working speed the PO talks to him he needs to stop and the conversation is longer than ~2 minute or if it requires focus, the dev will forget what he was doing. This means that we throw away at last ~15 minutes to get back in the zone. If the PO comes with a requirement change we throw away most of the work previously done. On top of that we re-introduce the initial >30 minutes overhead.

Mathematical conclusion:

  1. Interruption with design change – 150-400 Euros per hour based on how much work was done or can be reused
  2. Interruption without design change – 12.5-62.5 Euros per hour

A designer on the other hand, code (software architect) or visual (user experience designer or user interface designer), is a person made to have it’s cost shared with the whole team. On top of that can deliver the answer to the PO faster because the creation time it is much much smaller. Also, while the design is happening dev actually continues with his peak and pushes towards delivering a bit of functionality.

Now comes the more interesting part:

The quote from History: The Agile Manifesto by Jim Highsmith states:

“The Agile movement is not anti-methodology, in fact, many of us want to restore credibility to the word methodology. We want to restore a balance. We embrace modeling, but not in order to file some diagram in a dusty corporate repository. We embrace documentation, but not hundreds of pages of never-maintained and rarely-used tomes. We plan, but recognize the limits of planning in a turbulent environment. Those who would brand proponents of XP or SCRUM or any of the other Agile Methodologies as “hackers” are ignorant of both the methodologies and the original definition of the term hacker.”

My question would be. Why not delivering a proper sentence to begin with? Something like “Individuals and interactions in an optimized methodology”.

Because it wouldn’t sell just as well. In order to embrace something the business people have to see a big gain. The IT society is teaching us that in order to make money we must sell, because yes, money must come to us… LOL. We, as technical people, we suck at selling most of the time. The easiest way is to present something with less substance in order to look simpler.

How much process is enough?

Let’s say that the best practices do not exist because in order for them to be best they must apply to a scope. The scope can’t be the same in a 100 employees company, in a 5 employees startup and in a 15 employees scale up business.

My definitions of how much would be:

For documentation – “Enough to train any missing resource in the shortest acceptable time frame”.
It is normal for the people to come and go. The business must be ready to absorb the impact if the most senior resource leaves. The irreplaceable tend to become expensive after a while in multiple metrics (money, emotions, boredom etc).

For specifications – “Enough to avoid lost of focus or interruption”.
This goes hand in hand with the estimation presented above. It is more a matter of discipline. Look at the race between the turtle and the rabbit.

For deliverable – “The smallest piece of functionality that can be delivered to the customer which covers the smallest expectation of the stake holder”.
A developer has to develop. A PO has to figure this out with the stake holder. The QA has to look at the feature from the eyes of the customer.

In each of the three, every team member can improve enough the quality of the product without long working hours or stress.

How do we earn more money?

By have enough amount of resources with the enough seniority level. An individual chooses a position because he wants to. Not because he lost on a roll of dice. Let’s look again on how much we can save by not wasting.

Here is an example:

I am doing a work. My work has some results. When results are visible to :

  1. the team -> my hourly rate/team members that need it.
  2. a team member -> my hourly rage/1.
  3. the final customer -> this is investment, not expense

My conclusion related to “Individuals and interactions over processes and tools” in Agile

The conclusion of the first phrase would be that in order to increase the revenue we must make sure that:

  1. what we discuss is available in the same place to everyone that might need that piece of information when they need it.

The result is:

  1. we don’t interrupt ourselves
  2. we can set a goal instead of a deadline


Next topic “Working software over comprehensive documentation” tomorrow.

Have fun.

Top to bottom documentation

Hey there again reader, you are the best, the previous reader was quite hasty.

In the last post we have agreed upon the tools required in order to write less and achieve more in terms of documentation.

So far, in most of the cases when I got to work as a consult the documentation was missing altogether or it was composed of some screenshots at best. Usually from the Alpha version when they were used as wireframes, or mockups, or design documents, at this stage the naming makes little difference.

Let’s re-iterate the strengths we we must guide our effort on:

  1. Don’t understand again where you have left the work last time in order to continue. Reading the last phrase is a long enough waste of time.
  2. Document in the dead times of a project, such as waiting for a deploy or a bug fix.
  3. Create re-usable pieces of information
  4. Provide a base for automation

Hmm… yes… sure, fine, might be worth a shot.

As any top to bottom approach we should start with the WBS (Work breakdown structure). We can look at what we have but we don’t know the insides, however, the cover gives us a decent idea on how it might work. SO:

1) Create a blank document and start enlisting the elements you see now on the screen. Just write them, no smart things, we don’t even know what smart things we might have to do.

Good… there, we have a copy of the screen at hand. You can give this copy to any outsource and say “The new version must be the same as the old one”. Done, your screen is ready for a form of outsourcing or retest. Never had this before, nor this freedom. Didn’t take that long either. Yet, a screenshot would have been faster at this point :).

Please perform any sort of action on the screen that has an outcome in the state of the current screen and involves the project’s functionality.

2) Let’s look at the screen. It is very likely that some of the elements are common with the previous screen.

2 a) If there are common elements, stop now. Create a new page on the same level with the first one and move the already present elements there. We will just include them on the second and first page. Done, a bit of work is already done, without even knowing the project.

2 b) If there are no common elements, let’s create a link on the element from the first page to this second one. At this point we still have parity 1:1 with the screenshots if we would name the screenshots with a logic, else, after we forget their order the documentation might prove a bit more handy.

From here on, is just a rinse and repeat isolating common elements until we get to the end of the project.

Being here, if anyone asks you to provide a list of test cases for the UI part of the system, please, just point him to the documentation. If they want a list of functionalities, just follow the flow of the documentation and copy paste. Not that bad for some easy work.

Let’s go further, we know the UI. How about the functionality?

3) Well, find some time. Split your available time in 3. Go to any product owner, producer or management look-a-like team member and ask him what he can explain to you in 1/3 of your time. Use the second 1/3 to ask some questions or take some notes. Use the last 1/3 to add to the proper section that you already have.

Do not go to a developer. The developer will tell you how it works, not how the feature was envisioned. Maybe it wasn’t tested well enough, or never tested.

Rinse and repeat until you cover your project. There, now we have something similar to the exit criteria of the current application. Bits might not match. If they would have the documentation would have been in placed and you would have been hired as a QA.

4) Head towards the page objects automation model and observe that you already have all the bits in places. You know what are the common parts, what are the future test cases and what elements we already have. Even more, comparing the current functionality to the requirements presented on “3)”  we do have some bugs already.

All this with little to no thinking needed.

Hope it help you and pay attention to the italic part, some optimization is required there. Give it a thought.