Agile says no documentation.. or is it ?

Context

I prefer to say that the following topic is mostly relevant in B2B environment where multiple teams and multiple companies have complex dependencies between their software, code libraries, services, etc..

In my humble opinion, there is no real reason to avoid applying the following suggestions in other business models by making small adoption changes (which is, by the way, always highly advised when managing a change).

Anyway, here are my thoughts.

So, what's wrong?

Every manager, developer or third-party partner concerned by an Agile Project knows the "Agile Manifesto" statements:

I have to say here that unfortunately there are at least half of those statements who seems to be sometimes misunderstood;

Individuals and interactions over processes and tools

Working software over comprehensive documentation

Some people prefers to quote one or both of those sentences to forgive themselves for respecting any process, avoiding to write documentation `...because they are Agile`.

But.. is it ?

Documentation and Tests as "Products of the final Product"

There are business contexts where highly maintained documentation is a requirement, like some ISO certified companies because certifications about software documentation exists.

Do we really have to justify ourselves to produce High Quality Documentation for our business?

Almost any long-enough experienced developer have known at least once the difficulties to go through the `History of the Product So Far` when joining a project without proper project history, the stress about not knowing `Who's in charge of .. ?` because company processes are not available or `Sorry, that look outdated` when reading the available artifacts...

Is it really needed to prove the effectiveness of product testing in 2017 about increased maintenance costs when proper testing processes are neglected during development?

Every developer, business manager, change manager, release manager knows how difficult is to introduce a change (upgrade, improvement, etc..) when you have no proper way to measure the progress and regressions with scientifically valid indices; how hard is to estimate risks in that situation?

I'm not the first one writing about those subjects and probably won't be the last: a simple web search will give you a hint about how much this topic is not new in the IT world. I just want to share some ideas I came to while trying to figure out a scientific way to improve this situation when as a project manager you have to face it.

So here there are some simple ideas about a method to define ascending goals of quality during a project management. In the conclusions, I will discuss how this methods helps to increase documentation and testing quality because, in my humble opinion, quality cannot be stated as met without proper documentation and testing.

At the bottom of the page there is a `Glossary` for the acronyms used in this post.

Agile approach to improve Development Team Quality effectiveness

In my professional and teacher experience, all developers are very skilled in seeing "technically speaking" what code portions are in the need to be changed to meet a business goal but only a few have good visibility, given the full company overview, about impacts on short and long-term when a change they have made will be public.

Nevertheless, in some of the "Agile companies" I had feedback so far (from my own experience or by my peers during professional discussions or people who talked to me from conferences audience) and by my own judgement, the business and the "higher ranked" people are rarely actively involved in the planning of a sprint backlog so the actual selected items are choosen by the developers themselves leaving them in a decision-making role where only a few have the skills to do so.

The following statements are meant to be suggested in a inexperienced or very young Agile company where the adoption of those methods have failed to achieve the satisfaction level, probably because a proper coaching was missing.

Visibility, Quality, Stability, Verbosity, Scope

Any taken or proposed change released to a company customer must be documented with no exception and shall not introduce regression of any form.

We want to know exactly why we added or changed any stuff, how we managed to test it and how do we validate it before taking any action.

We also want to be sure that no code or convention change is introduced in production environment for any reason excluded company decision (that everyone should approve!) or when customer asked (and paid) for it.

We want to check that any changed convention or code has been seen and adopted by all concerned actors in all teams during all phases to keep quality as high as possible while maintaining interoperability between all the concerned individuals, all software components, all partners, all external services, etc..

How to achieve that?

Given the Agile statement,

Individuals and interactions over processes and tools

The best tool is NOT having "no tool"; the best tool is the one where all concerned actors are the most comfortable.

I'm here to propose a "droppable" support, something which is used between each step but needs not to be kept: as such there is no need to make it too much formalised, thus fast to be shared and maintained (and finally, dropped).

Presenting the Quality Manifest (or QMF)

Quality is said to be fixed in any Agile managed project during the full product life cycle. Sometimes the "fixed" part of the statement is intended as "not to be changed (until the end)" and here is where I disagree.

Quality should never decrease

That said, this is a big difference from fixed rate quality in terms of global quality goals.

What is a QMF ?

It is a discussion of an improvement or a change, proposed or already scheduled, shared and maintained in a way where every concerned actor is comfortable to do so.

Quality Manifest is not just another document, it’s a method.

It is a (kind of "plug-in") method for Agile change management because it help us to follow some major guidance before entering the production `tunnel effect`.

So here are the suggested guidelines to think about twice before going forward to any idea involving a change:

• why we added or changed (or wants to add or change) any stuff
• who’s going to contribute for this change to happen (and should be aware of it)
• how we manage to test it (and be sure no regression is going to happen)
• how do we validate it before taking any further action (and be sure everyone agrees and won't be a victim of my decisions)

That said you want the information to be as short as possible, exposing your arguments to the most essentials whilst being compliant to those guidances.

What is NOT a QMF..

A QMF is not a replacement of a CR: it is a lower abstraction level, less formalised and collaborative step in the company process.

A QMF is not a replacement of code comments: it just allow every concerned team or actor to be OK with the change BEFORE proceeding but code still need to be well commented.

A QMF is not a replacement of technical documentation like public or internal API.

A QMF is not a Change Log, it is intended to be used DURING the phase of Analyse/Design/Study of a change but a Change Log should be maintained AFTER the code has been adopted.

It does not replace CAB process.

It does not helps plan changes in terms of time scales: it does helps in terms of dependencies and risks.

Recommended Guidelines

Any format or any appearance is fine with the QMF since it is intended to be a method and can be materialised as a document, a forum, a drawing board, a chat channel...

• any concerned actor should be comfortable with the way the QMF are shared and maintained.
• should be versioned to allow concerned actors see the changes since their last review.
• should be easily shareable to allow concerned actors to find it and contribute to it
• should prevents typical problems like lost of data, people missing updates..

Since it’s intended to be a droppable support, there are no problems about having multiple QMF types over multiple formats and materializations during the company lifetime: feel free to experiment and change it as long as it fits in the recommended guidelines.

About its life cycle

A QMF is a not-to-be-kept support, it is intended to be:

• created before the change
• maintained until change plan is final
• updated during the implementation
• released with the production
• abandoned

Once the change(s) of a QMF have been integrated in production, the QMF is no longer needed and can be dropped or transformed in a more conventional document and archived for future references as a Knowledge Base (KB).

When a QMF should be shared or maintained..

There are some use case where a QMF might not be necessary and some cases where it should be mandatory. Following are some recommendation but it is really up to the `Good Practices` principle that you should be aware if a QMF have to be shared or not.

Changes that might be wise to be discussed via a QMF are:

When modifying..

• Any changes who change behaviour of any, directly or indirectly, exposed public behaviour.
• Any change to behaviour of any object exposed to other developers and teams.
• Any screen or ergonomic been already in production or already approved by the customers.
• Anything missing documentation and testing, or whose documentation and tests might get outdated afterwards.

When adding new stuff

• Any new API, regardless if this is for internal use only or public.
• Any new screen, tools or new object serving any new purpose regardless if this is for internal or public usage.
• Any new introduced framework.

Changes that might not need a QMF are:

When modifying

• Any change operated internally, not changing any behaviour of the current public or exposed object.
• Any change operated in a confined set of elements not exposed to public usage and not used by other developers.
• Any optimisation in a confined environment which does not break any other previous rule.

When creating

• Any POC for demonstration purposes.

Conclusions

So, how does the QMF helps us to improve documentation and testing thus global project quality?

To be honest, the scope of the QMF is far beyond the simple documentation and testing because in the Agile methods, these topics are largely taken into account: think about the `definition of done`..

The concepts behind the QMF are meant to improve the cross-team cross-companies scenarios where, in my humble opinion, common Agile methods focus on one project and one team. I might be wrong about this and I'm willing to discuss and change my mind in the comment sections, if ever.

When actors of a (proposed or planned) change shares a QMF, they are invited to share it with all concerned actors and that includes not only developers but also business actors, third parties, decision makers, etc.. effectiveness is improved because people are solicited when the already involved gents think they should be and recognize a value in their involvement! It does help involved actors to understand the range of their actions and give them higher points of view about their work into the company.

The point here is that documentation and testing are meant to be managed as products of the final product (as said earlier) and should be enlisted as impacted by changes, when they are, in the guidance checkpoints.

Because each product have its own actors whose can be impacted by a change somehow. As such, the documentation and the testing products of the final product should be maintained during each phase of each user story and for each backlog element instead of single separated tasks somewhere in the final product development life cycle.

Of course, documentation and testing must add a value into the final product: there is no point in documenting the obvious or the already established standards as much as there is no point in testing an already tested software component twice.. again, the `Good Practices` principle still apply.

Glossary

• QMF: Quality Manifest
• B2B: Business To (aka "2"~>"two"~"to") Business
• CR: Change Request. Used in this document as a synonym of Business Requirement, Sprint Backlog, Software Specification, Maintenance Task, IT ...
• CAB: Change Advisory Board.
• POC: Proof of Concept

Annex

If you made so far, I want to say...

Thank you!

There is a lot more to talk about this topic.

I have already experienced some real life implementations during my career as a professional and as a university teacher, I could share some prototypes of QMF guidances and their areas of apply.

I would like to share some complete examples of real life work-flows about common QMS life cycles: how to start it, how to share it, how to make it evolve and finally die.

There are some interesting points to be approached about the actors roles to be played in this QMS game, like:

• Decision Makers
• Project Managers
• Concerned Actors
• Reviewers, Coach, Maintainers?

What are theirs responsibilities and how each of these roles can contribute into the final global quality goal?

I have some theories about how to use it for risk management, planning and charge management, change management...

Let me know in the comment section if you are interested into this proposed approach and I will be glad to share the remaining bits.