Too Many Documents

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 lose 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?

What are the chances that one will be changed and not the other? What are the consequences?

What about the requirements? Is it really so hard to 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. You don’t even have to switch to another file!

Of course you can use tools to create the illusion of integration of the documentation sources.

But it’s not the same as actual integration.

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

What about you? Did you find ways to reduce the number of documents required to develop? If so, please share in the comments!

In the past few years, I haven’t stopped thinking about what makes Agile work. The Agile Manifesto was written by masters in the field, and those ideas have stood the test of time. However, while the manifesto is quite rich in ideas, it’s still too vague for many. And others just do not know how to start the journey…

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.

The Groovy web console lets you run Groovy scripts without having to install Groovy. It also maintains a script library: http://groovyconsole.appspot.com/ and runs on Google App Engine.

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?

I enjoy contributing to the knowledgeosphere on the web. I stumbled upon an article I had read a few months ago, by Mike Bria about Joshua Kerievsky’s concept of “Sufficient Design”. I took some time to comment on it. Since you’re here, I promise you won’t regret following this link: http://www.infoq.com/news/2010/05/sufficient-design

Yes.. How do you do that? Twitter? You stop reading it for 3 days, and you get back with hundreds of unread (and mostly useless) tweets. News aggregators: TechCrunch and others? Better, but you don’t really choose which specific contents are of interest to you… RSS? Better… but which reader do you use that allows you to show at a glance what’s new and worth reading.

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)

This morning, I was listening to my partner telling the story of my 5-year old daughter’s first bicycle ride to her mother… and this got me thinking about programming.

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!

I found myself asking for written specifications from our major customer the other day, and it made me shiver… What on Earth was wrong with me? Wasn’t I able to cope with fuzzy requirements anymore?

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!

I feel that 2010 will be a big year for me. As I am reflecting on the future, I am also watching junior developers in my team, and this has led to some reflections on some of my strengths as a software developer. I think one of the main ones is creativity. I think that one of the common traits of promising developers is that they develop applications to learn a new technology, and that the result is stunning. While I was thinking about my early steps in the profession, some 20 years ago, memories have popped up, one by one, of noticeable innovations I made in my first jobs. Here’s a list of some of the ones I remember…

  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).

A great talk on Coffee and Software development by Linda Rising was posted on InfoQ. Watch it now!

Quand je suis allé en vacances à Cuba, j’ai choisi un livre qui sortait un peu de mes lectures “sérieuses” mais pas trop. Ma mère avait vu un entretien à la télé avec Daniel Tammet, écrivain autiste génial, et m’avait incité à en apprendre davantage – c’est à dire à lire le livre dont il faisait la promotion.

Dans ce livre, il raconte que s’il est capable de réciter les 22000 premières décimales de Pi, il est en revanche souvent incapable de reconnaître le visage de ses amis. D’un côté il est capable de réaliser ce qui paraît à la grande majorité d’entre nous tout simplement incroyable ; de l’autre, il est incapable d’accomplir une tâche qui nous paraît tellement banale que nous ne réalisons même pas que c’est est une ! L’explication qu’il donne à ce phénomène est une “attention” et une “obsession” différente – dans son cas, il a une obsession pour les chiffres, auxquels il attribue une couleur et une taille. La faculté de reconnaître un visage, quant à elle, recourt à une capacité de synthèse – faire abstraction des détails pour voir le tout – qui lui manque.

Plus loin dans ce même livre, – et c’est là que nous arrivons au titre de cet article – il a un chapitre un peu fourre-tout (“Food for Thought”) dans lequel il étale ses réflexions sur divers sujets de société et d’actualité. Si les premiers chapitres m’ont donné des coïts intellectuels multiples, celui-ci, en revanche, m’a laissé un peu … coi. Partant de bons sentiments (un cri du coeur pour combattre l’illétrisme, mais surtout ce que j’appelerais l’”inchiffrisme”), il y dénigre wikipedia et les lotteries, machines à sous et autres jeux de hasard.

Il y démontre que les gens seront statistiquement toujours perdants à tenter leur chance à ces jeux. Il ne lui vient par contre même pas à l’esprit que des gens pourraient jouer, non pour gagner, mais pour éprouver certaines sensations et émotions. Je ne veux certainement pas défendre les joueurs – je n’ai moi-même jamais joué et trouve effectivement cela stupide – mais je comprends pourquoi certains de mes amis le font. Il renforce par contre efficacement son argument qu’il n’arrive pas à “voir le tout”.

Pour en venir au coeur du sujet. J’ai souvent observé des projets initiés comme on joue aux machines à sous. On met de l’argent, on tire sur la manette, on regarde les lumières s’animer et les figures défiler, puis on crie de joie si on a gagné. Sinon … on recommence. L’autre jour, je regardais jouer un ami dans un bar. Il gagnait 17$ pour une mise de 2$. Je le voyais alors avec horreur rejouer immédiatement, et jouer encore jusqu’à ce qu’il ait tout perdu.

Mon horreur venait bien sûr de nos perceptions différentes. Pour moi, avoir une mise de 2$ dans la machine était comme un accident : “Mon dieu, 2$ sont tombés de ma poche dans cette machine !” S’il en sort 17$, je trouve cela merveilleux ; je transforme cet accident en opportunité et je récupère ma mise, plus 15$ ! Pour lui, par contre, un gain inférieur à 30 ou 40$ ne justifie pas l’arrêt du jeu. En fait, soyons honnêtes, je ne peux pas vraiment expliquer ce qui se passe dans sa tête parce que je ne le comprends pas vraiment. Le fait est qu’on n’apprend rien de ce genre de jeu. On a autant de chance de gagner la première fois que la seconde, etc … Il y a autant de raison de s’arrêter après avoir gagné 15$ que la fois d’après, et ainsi de suite.

Il m’a semblé que beaucoup de grandes organisations traitent leurs projets comme des machines à sous. C’est à chaque fois un jeu de hasard.

La différence, cependant, c’est que pour les projets, on peut améliorer progressivement ses chances de succès. Pas avec les machines à sous.

Le PMBOK conseille de documenter et d’utiliser les leçons apprises, Agile s’appuie sur des équipes stables et des rétrospectives, Lean met l’accent sur l’amélioration continue des processus. Cependant, les organisations qui utilisent vraiment ces mécanismes de façon conséquente sont bien rares. Je vous invite à faire part de vos expériences qui démontrent le contraire – ou non.

Peut-être est-ce le temps de comprendre ce qui différencie les machines à sous des projets et programmes.

1 2 3