Too Many Documents Required To Work

(The title of this post comes from one of the Twelve Tasks of Asterix)

Imagine I am working on a research paper. In order to work on this paper, I need to use 7 different document sources:

• 1 laptop
• 1 iPad
• 3 paper documents
• 1 whiteboard
• post-its

Now, imagine that each of these items is physically located in a different room. That would be silly, right? Not only would I loose time constantly going from one room to another, but there would be a high risk of errors, distraction, delays, low morale… Eventually I would just eliminate some sources of information altogether, using whatever the strict minimum is that I need to produce anything I think I can get away with, no matter its quality.

In order to do his/her work, a developer very often has to use quite a large number of sources of information:

1. Source code
2. Unit tests
3. Integration tests
4. Functional tests
5. Wiki describing the service interfaces
6. Design diagrams
7. Architecture diagrams
8. Business rules
9. UI Mockups
10. Framework manual
11. Deployment console to deploy on the development server

No wonder developers love to have 2 or 3 screens, so they can at least keep all those windows open and navigate from one to the other without losing context!

Still, don’t you think it’s overwhelming? Especially when you know that many items can be merged together.

Take the service interfaces that the components expose, and the source code of those components, for example. Why duplicate the information, especially at two different locations?

How likely do you think one is to be changed and not the other? What are the consequences?

What about the requirements? Can you really not find a tool that merges both the UI and the rules?

You can think of tools such as Concordion to document your specifications and make them executable, effectively merging the business rules and many tests.

Even better… I stumbled upon PHPUnit 3.x and discovered the @assert annotation. You can write the tests just above the method body:


/**
* @assert (1, 2) == 3
* @assert (0, 0) == 0
*/
public function add($a, $b)
{
return $a + $b;
}


Wow. What a great idea. No need to even switch to another file!

Of course, you can use tools to create the illusion of unicity for the documentation sources.

But it’s not the same as actual unicity.

For example, if the tool is Eclipse and someone in the team does not use Eclipse, then you have the risk of discrepancies induced by the different sources of information.

What about you? Did you find ways to reduce the number of documents required to develop? Please share!

I had the opportunity to share some insights with the community at the Agile Tour events in Montreal and Quebec City. After years of thinking about how to get better at my (software development) craft, I tried to summarize what I had learned and turn it into two introductory workshops.

At the Montreal workshop, I invited people to think about what Agile brings to the table, its goals, and how it works. Of course, some code was involved. Otherwise, it wouldn’t be about Agility. It would be about Yet Another Process. Slides are available, though I doubt they would be useful to those who did not attend the workshop.

At the Quebec workshop, I invited teams to think about specific systemic problems they have at their workplace, and give some basic tools to solve them. The most important ones are to allocate time to LEARN and THINK FOR THEMSELVES. Those are the first steps to introducing changes. I promised to give some more material next week, so if you attended, watch your inbox!

I would like to thank all the participants for their ideas and feedbacks. I would also like to thank the original creators of Agile Tour (http://www.agiletour.org), my fellow Agile Tour Montreal 2010 organizers and those of Quebec city. Thanks for the numerous positive tweets and blog posts..

And now, let’s get some rest.

A new GDate class with a toString() method that prints the date using the ISO 8601 format with the T replaced by a space: yyyy-MM-dd HH:mm:ss.SSS

It comes with unit tests; are you able to come up with a leaner/groovier implementation?

Well… I’ve just found THE thing. Drumroll…

It’s called FeedSquares and it’s a Google Chrome extension for Google Reader, available here

“Try them, try them, and you may! Try them and you may, I say.”
— Dr. Seuss (Green Eggs and Ham)

My partner was explaining that my daughter got really upset when she found that her mother had stopped holding on to the bike without letting her know. Obviously, my partner was telling the story to provide information to her mother (“your granddaughter can ride a bike!”), but she was also telling it with jokes that entertained both her mother and my daughter. Clearly, those two audiences required very different kinds of humour. But she managed to make it fun for both of them.

When my 2-year old son tells a story, he usually only sticks to the facts, as in: “I fell down on the floor”. This makes a decent story coming from a 2-year old. Not quite so from a grownup. An adult is expected to add some ornaments to the flow of words in order to make it interesting. But poorly chosen ornaments might make it incomprehensible for my son. From the thousands of possible ways to tell a story, the good story teller has to find the discourse and tone that intersect with her audiences’ requirements for a good story.

Some people are really good at that and are paid hundred of thousands of dollars to host family TV shows where they make parents and kids alike laugh their heads off. Similarly, the best family movies are the ones that have good jokes for all ages.

So it goes for programmers.

Novice programmers write for the computer and only for the computer. Experienced programmers take into account many more requirements, while still making the code work for the computer. As Kent Beck’s “Implementation Patterns” book probably explains pretty well (I have only listened to an interview where he talks about the book, but not actually read it yet), and as most experienced programmers have more or less consciously figured out by now, code is not only written for the computer, but also for your fellow programmers.

I remember writing my first program in Bill Gates’ BASIC (indeed!) language. I certainly had to fight so hard to make my intentions understood by the computer that, even if I wanted to, I didn’t have any energy left to make my intentions understood by any human being. Most beginner programmers will be like first-time victims of a theft at a police station in a foreign country. They will focus on providing the most specific facts about where their belongings were before they were stolen; they won’t care or be able to make the story a fun one to listen to.

Code is (or should aim to be) much more often read and modified than written for the first time. While the beginner programmer digs through more and more code, he may start to grasp that some modules are much easier to understand and modify than others. For example, he may realize that properly naming variables to reflect their roles, instead of just using “s” for a string or “i” for an integer, help a lot when understanding code, and make it both faster to modify and less error prone. (It might also help to be curious and to read experienced programmers’ advices and thoughts on the matter)

Experience grows with time and feedback and a senior programmer’s code will answer many more stakeholders’ requirements than just the computer’s. Code will have to be maintainable. It will have to be easy to test by automated tests and QA engineers. It will also have to provide good hints about causes of failures to support engineers by logging informations properly. It will also have to scale well and use resources cautiously to keep CxOs’ happy. And so on…

A senior programmer understands that code is not just bits for a CPU to process, it has a much wider and more humane audience. At the same time, it takes a lot of practice and/or talent to write code that’s music to the whole company’ ears!

The answer is YES.. BUT…

The goal of the “Embrace Change” motto (this is the subtitle of “eXtreme Programming Explained 2nd. Ed”) is to account for the fact that the cost of changing a system may not grow exponentially as is commonly thought, and that changes are always for the better. As a matter of fact, changes are requested at a time when users/customers know better what the system should do (because they have had the chance to play with pre-releases and think about the system some more… or because their understanding of the market has evolved), and developers’ ability to design and implement features is also better (because they have learned to work together and learned the tools and technologies).

BUT…

It doesn’t mean that users/customers should not think about what they want, explore their options, and keep track of their discussions/reflections. It just means that they should do so with the expectation that they will probably have even better ideas later on… and that those changes will still be easy to implement by their Agile developers (just change a few tests here and there, think about how to fix them, and then fix them!).

Also, documents serve a purpose: they prompt thinking.

In our case, requirements must be run by multiple parties, who cannot always sit in the same room at the same time to validate their shared understanding about what the system should do. Documents alone are far from the best way to communicate requirements, but they are better than nothing. In particular, they are better than having developers guess requirements, write tests and code, then deploy and ask for feedback, then do it all again until all parties finally realize they should sit together. The process of identifying all stakeholders is a very important step in the  PMBOK® Guide, and one that is not covered by XP or, for simplicity’s sake, Scrum.  Skipping the stakeholder identification step will always generate unnecessary changes and waste.

Embrace Change: yes! Invite Change… Not sure!

1. As the fourth hire in the technical support department of a then-fast growing European software development editor, and not knowing anything about the tools I was supposed to mentor customers on, I had to learn the tools fast! As I found the paper-based system to handle calls pretty… outdated, I started to develop a ticket-management system using the technologies I had to learn. The result was an application, called NS-Appel (Call), that came complete with easy ticket editing, knowledge base and a search engine. The whole team progressively adopted it, and it became the standard application for the next 4 years, while the department grew as the company’s customer base grew exponentially after that. The technical support team later attempted a long and painful rewrite to showcase the company’s latest object-oriented development tools, but (unfortunately?) the result never matched the reliability and performance of NS-Appel.
2. At approximately the same time, I became interested in a new word-processing library and figured that I could use it to create complex reports, embedded in rich-text documents. I went on to develop a templating engine that would be the equivalent of forms and macros in a modern word processor.
3. When I became a consultant on the company’s new Integrated Development Environment, I realized its lack of tooling. I developed a bunch of utilities that plugged into the IDE, and provided features such as a Google-like search engine that supported regular expressions and searched just about every artifact in the source control repository, and a source control log analyzer. These tools quickly spread among my peers, and up to customers (which created some problems when users started playing with the much too powerful global-replace feature!)
4. Others started as customer requests, but very quickly and by far outgrew the original requirements. I developed an automated remote builder/deployer, something that I find still missing today in modern IDEs. Using FTP and RSH, the extension copied the generated, portable, C sources, from a developer’s PC to a target mainframe or *nix machine, and remotely triggered the incremental compilation and linking of the application. The whole process was monitored on the PC, with logs being displayed in real time.
5. This is not counting the applications I developed while still a student or even (much) before that: a drawing tool with unlimited undo/redo and various games in Basic or Assembler. This included one I created a in a few hours, but played with for a few months, that I called Greta-Kill-Kill. It was dedicated to a Biology professor I developed a love-hate relationship with (unbeknownst to her, of course).