Agile Development Ramblings: Part IV
The Documentation and Handover

Up to this point, we had been very successful. As far as the AU's were concerned, we had done a great job. They were all happy to sign off the finished product. However we had not built the final, deployable product. While not strictly speaking a true prototype (the vast majority of the front end code was planned to be kept rather than thrown away) everything behind our Session Facade was to be re engineered. This was to accommodate a wider and separately architected Strategic Portal Framework based on Websphere Portal and an SOA based Model / Persistence store.

In addition, this further development work was not to be conducted in-house and was instead to be handed to a development partner with little Agile experience. Further compounding this was the fact that further development was not scheduled to begin immediately. The original plan had been for us to verbally hand over as much information as possible. This was now impossible. Instead, we had one week to write it all down. To be fair, an awful lot already was. Indeed a great deal was already encoded in things like Maven. What we didn't have was anything about the architecture. Nothing up to date or accurate anyway.

The Agile Architect?
The point of Agile programming and development, I have learned, is that “the Code is the Blueprint”. Roughly translated, this means that everything you need to know about the resulting application is in the code; be this the code itself, the comments, the javadoc, or all the supporting (usually auto generated) xml and database schemas and properties files. This is all well and good, but to be able to understand it, you need to know Java and SQL. You also need a lot of spare time and better hope the developers write legible code.

This wasn't what the development partner was expecting, and so we had to go about reverse engineering things such as Logical Data Models, UML Diagrams, textual descriptions of the Architecture etc. This wasn't very Agile. We had been lucky in that we hadn't had a requirement to continuously produce these artifacts throughout the process. It would have hampered our progress considerably, always updating them and making sure they were accurate. However, it was clear why each and every one of them had been requested.

There is a current trend in the Agile world against the “Architect” and I agree that it is a grossly overloaded term. However, not everyone can, or should have to read code to see how something works. There is a requirement, even a need for there to be an intermediary between the Business Analysts and the Developers. There is a need for the production of logical and conceptual models which avoid implementation detail but provide enough data to inform strategic discussions as well as the nuts and bolts of building the thing.

A major benefit of Agile is that developers are plugged into the eventual users of their system, rather than being obscured from them by the analysts, architecture and architects. However, the current model of an architect is the “Big Up Front Design” / “Big Requirements Up Front Requirements” type of person which Agile has shown to be lacking. The old “develop to a paper plan and an interface” model Developer is changing, and I believe that Architects need to do the same; perhaps adopting a hybrid role like that which I played on this project will emerge – what I call the “Side On” approach (as opposed to the traditional “Top Down” or “Bottom Up” approaches). Then everyone has a relationship with the users. Perhaps not. Time will tell.

Either way, this isn't the place to go into this in depth, but it's something which I believe you'll see more and more debate about in the months and years to come. I personally plan to learn the lessons of Agile and try to apply them to my other kinds of engagements from now on. So what are the big lessons I've learned over the last 14 weeks?

Lessons Learned

1. Remember the “10 Commandments” [link]
2. While this project benefited from a number of favorable conditions (small and discrete and defined scope) I firmly believe that Agile methodologies can cope with far larger projects and less well defined scope and requirements. They are designed to manage the risks this brings while embracing the increased flexibility.
3. The quality was evident – we never had a major bug appear during demos to users. this instilled confidence in the Ambassador Users and it also helped the process in that the users could "play" with the system and understand the evolving requirements.
4. Have a demo box permanently available. This was requested a lot by our AU's but it was too difficult to achieve. But would have helped to get more users have hands on earlier on in the process, and help with wider user group buy in / adoption.
5. Don't however waste time setting up the demo box again and again – automate it (with Cruise Control and Maven)
6. One important aspect of an iterative process is that it can be continually reviewed throughout the project lifecycle. The team took advantage of this, resulting in an improved format for the workshops and new implementing reporting and testing procedures.
7. You must be disciplined

· Think about what you are doing and ask “Does it add value? Does it help towards delivery?”

· We didn't always follow our own standards. Sometimes it might have been better to enforce things with Subversion, Maven, PMD and Checkstyle.

8. It is essential that different user groups respect and understand the prioritisation objectives of others. This was certainly the case on this project.
9. It was also important that the Ambassador Users had the appropriate skills and experience to drive the project requirements forward and they were empowered to make decisions pertaining to the prioritisation and implementation of features.
10. It was of benefit to the AU's themselves to be round the same table though they come from different backgrounds and have different requirements. They gain a shared understanding through their participation

· What did the close developer / user bond require?:

(a) Developer communication skills – of highest importance – else you build lots, but you build the wrong thing

(b) Delivered code must be understandable to those who will interact with it

in the future

(c) Every feature built must be deployable - Even if the end result is not deployable (i.e. ours had no security so wouldn't go live)

(d) Buy in and understanding from all – Leads to a shared sense of responsibility

(e) Honesty from all – If you don't understand, say so; If you don't like, say so; ...

· What did the close developer / user bond result in?:

(f) It positively affected developers understanding of what will happen to their product once work is complete

(g) The developer sees who will use their system, rather than imagining them.

(h) The developer becomes aware of the change management, training and update issues after their work is complete

(i) Everyone is empowered

(j) Greater visibility for all participants

11. I, and others were amazed how much could be achieved in such a short period of time.
12. The lack of documentation in Agile projects makes people used to traditional approaches feel uncomfortable.
13. Communicate, communicate, communicate
14. You are not your code. Take pride in what you do, but let go once you check in.
15. Keep it simple. If it gets complicated, refactor.
16. Naming is very important. Agree on a strategy early on, then stick to it. If possible, enforce it with Checkstyle
17. Identify and stick to standards and best practices throughout
18. Tooling is important. If there's a plugin or a Wizard, you can save time.

· Frameworks save time, but add complexity. We didn't use one for MVC as things for us were simple.

19. Only use tools and frameworks as and when required

· But make sure you don't make them harder to adopt in the future if you decide to not use then from the get-go