Agile – Extreme Programming – documenting implementation

I would recommend reading a few books to get started.

A general book about the art, craft, and engineering behind software development is The Pragmatic Programmer: From Journeyman to Master. This book talks about everything from dealing with people to tool support for your development. It covers a lot of ground in a very small package, and I even reread this book from time to time. The advice is applicable to everyone in software development, from the programmer through the project manager.

Rapid Development: Taming Wild Software Schedules. It's the book used in the process and project management course that I took, and it covers a number of major process models and methodologies, when they apply, and commonly accepted best practices for managing projects. However, like most work, it focuses on team projects as opposed to individuals.

On the coding side, Code Complete: A Practical Handbook of Software Construction is a recommended read. It focuses on how to write good, clean code, with concepts that apply to a number of languages. The emphasis is on procedural and object-oriented programming, but the advice can be applied to any language or paradigm.

For designing object-oriented software, the classic texts include Design Patterns: Elements of Reusable Object-Oriented Software and Refactoring: Improving the Design of Existing Code. There are a number of books and resources in this field, and a lot of design decisions are driven by the technologies you are using and the requirements of your project. For software system architecture, a classic text is Software Architecture in Practice which discusses topics ranging from architectural views to product line development. That was the book used in my software architectures course, but some professors were using Software Systems Architecture: Working With Stakeholders Using Viewpoints and Perspectives in its place.

However, you can't just read these books. The important thing is to apply what you have read to your projects at work, school, and at home. You can read all you want, but if you don't apply your knowledge, it's meaningless.

On my projects, a lot of what I do is driven by my goals, either in terms of personal development or the requirements of the project. You aren't going to find a one-size-fits-all methodology or process, so the best bet is to look at commonly used best practices, find out what works for you and your team, and learn from mistakes for future projects.

XP doesn't explicitly call for the creation of a model, but it doesn't say that one should never be produced. If developing a model helps you to build and then document your system, it should absolutely be done. The difference is that Agile Modeling has a different focus than system modeling in a plan-driven environment. In fact, the Agile Modeling site even addresses specifically how you model in an Extreme environment.

Agile environments take a more Lean (in the same sense of Lean engineering or Lean manufacturing) approach. Some of the key tenants include reducing waste, deciding late, and delivering fast. In order to eliminate waste, only the required documentation is delivered at the appropriate granularity. If you produce a work product, that work product is expected to ultimately add value to the customer - waste is considered anything that doesn't help add value to the person paying for it.

In fact, the XProgramming blog article you linked to supports this:

You may well need some nicely formatted UML for your project...If and when you really need these things, then by all means you should do them. But inside your collocated Whole Team, you most probably will not need them, because the information you need will be communicated through the more effective medium of conversation.

The Martin Fowler article that you linked to also supports this:

Certainly XP de-emphasizes diagrams to a great extent. Although the official position is along the lines of "use them if they are useful", there is a strong subtext of "real XPers don't do diagrams".

A central idea of the agile methods is "individuals and interactions over processes and tools". You don't follow a process or use a tool for the sake of following the process or using a tool. If the task that you are working on does not add value or if it doesn't produce something that is useful to someone (either the customer or another engineer), then you don't do it.

Martin Fowler goes on to say:

The primary value is communication. Effective communication means selecting important things and neglecting the less important. This selectivity is the key to using the UML well. ... A common problem with the common use of diagrams is that people try to make them comprehensive.

Again, same idea. The purpose of any documentation is communication. If you are producing things that don't help you communicate the system, why are you doing it? Don't focus on every little detail, but focus on communicating a message that provides useful, value-adding information to someone else.

Even later in the article, Fowler goes on to note that one of the problems with CASE tools is that they can fall out-of-sync. As soon as the code and the documentation fall out of sync, the document adds no value. I'd even take this a step further and say that it adds negative value, as it provides false and misleading information to anyone who tries to use it to make a decision. If you have a process to maintain synchronization, that's good. However, if you don't and you do let your documents fall out of sync, this brings up another question: why do you have them? They clearly aren't being used, or else they would be maintained.

Rather than some other model-driven methodologies requiring the models, even if they don't necessarily add any value, XP calls for spending time and resources on things that actually help you deliver value to the customer/client. If you can justify that certain models actually do add value to your project, then by all means you should produce them. However, you shouldn't be producing models that duplicate other information or don't add value.