WeBlog
  • Agile Culture
    • Agile methodologies
    • Skills and expertises
    • Creativity and innovation
  • Management and Organization
    • Leadership
    • Work ethic
    • Team collaboration
  • Tech and Digital
    • DevOps and Craftsmanship
    • User experience and Digital Delivery
    • Data and Cybersecurity
  • EN
    • FR
No result found
View all result
Discover Wemanity
WeBlog
  • Agile Culture
    • Agile methodologies
    • Skills and expertises
    • Creativity and innovation
  • Management and Organization
    • Leadership
    • Work ethic
    • Team collaboration
  • Tech and Digital
    • DevOps and Craftsmanship
    • User experience and Digital Delivery
    • Data and Cybersecurity
  • EN
    • FR
No result found
View all result
Discover Wemanity
WeBlog

Is Documentation Relevant in an Agile Context?

by Bruno Delb
01/2022
in Tech and Digital
Is documentation relevant in an Agile context?

Documentation is still too often seen as superfluous or as a constraint. On the contrary, adopting a Documentation-as-Code approach offers a potential gain in time and efficiency for teams in an Agile context, in particular, to ensure the continuity of the code and the software infrastructure.

1. What if the documentation was part of the source code?

Documentation is often a delicate subject in an Agile context. Based on the second principle of the Agile Manifesto: Some consider “Functional software rather than complete documentation” as counterproductive. However, in my opinion, this principle does not mean that documentation is unnecessary, but rather that “you must not sacrifice the quality of the software to produce it.”

Naturally, the team’s primary objective is to produce the software, and the aim of the members recruited later is to maintain and modify this software. But how could they achieve this without documentation? You could say that the code in itself must be sufficient to understand the essentials … but even when the name of the objects is explicit and well-chosen, that is far from being enough. However, the problem is that producing and maintaining documentation takes a long time. So one solution could be to consider the documentation as part of the source code.

2. Good documentation practices

But before discussing the concept of Documentation-as-Code, I would like to share a personal experience that I think may sound familiar to you. A banking solution provider employing both service providers and interns had experienced high staff turnover over a very short period. Applying the principle that documentation is only written when several people ask for it, it was practically non-existent. However, when several team members left, there was, of course, a transfer of knowledge, but it was short and insufficient.

Lacking a clear understanding of the software architecture and the infrastructure, the new team then encountered numerous difficulties in modifying the source code. Although the application was deemed to have been sufficiently tested, it turned out that some unit tests failed but did not block the release, and automated functional tests were mostly disabled. Obvious consequence: significant difficulty in getting out releases because most of the changes had side effects on the application, introducing bugs or regressions. The actual content of the releases was unclear, the release notes being vague and often incomplete. And we can add to that the pressure of management, the working atmosphere and the deteriorating morale of the team which contributed to further reducing its ability to implement the functionalities.

So it was essential to establish a technical debt reduction project, which, notably, involved establishing new good practices. The key actions undertaken were:

  • Automating the generation of architecture diagrams from markdown files in the git repository, making them easily accessible to developers.
  • Generating test reports and displaying them in a dashboard, making them visible.
  • Implementing a template for commit messages and automatically generating release notes making it possible to check what is delivered.
  • Drafting a coding convention and implementing static analysis to ensure that these rules are respected and automatically producing a code quality analysis report.
Related post:  Microservice Architecture: Definition and the Many Reasons to Set It Up

Implementing these good practices allowed the team to re-deliver successfully, ultimately absorbing the technical debt. Above all, confidence and a favourable working climate were restored.

3. Documentation-as-Code or DaC

So we can speak of Documentation-as-code, DaC or even Doc-as-Code. But how can we define DaC? Through practices that apply coding techniques to writing documentation:

  • Git
  • Code/markdown
  • Reviews
  • Tests
  • Follow-up on issues

Taken together, these practices provide a reliable definition of documentation. But it can also exist in several forms:

  • User Stories: this is documentation.
  • Source code: this is documentation if it is correctly named and follows the coding standards.
  • Source code testing: Source code unit testing is documentation… if the tests are explained, and their limits are specified.
  • Test plan and test results: this is also documentation.
  • BDD: Gherkin files (.feature) are living documentation.
  • X -as-Code (including Configuration-as-Code, Infra-as-Code, Security-as-Code…): this is also living documentation. Here are some examples: Ansible playbooks, Terraform tf files…
  • Configuration files, if they are user-readable.

In this form, Documentation-as-Code has several major advantages:

  • Genuinely useful documentation is kept up to date while requiring minimal work.
  • Documentation is brought in earlier, in the same way as testing (we speak of “shift-left”).
  • Knowledge is shared.

4. DaC: Four characteristics and four practices

We can recognise four essential characteristics of Documentation-as-Code:

  • Objective: Each piece of documentation must have a purpose.
  • Simplicity: the documentation must be kept simple.
  • Stability: the documentation must be stable; it should not be created either too early or too late.
  • Executable: Documentation should be executable when possible, based on tests.

In parallel with these four characteristics, we can also identify four practical applications of Documentation-as-Code:

  • Create living (or executable) documentation as early as possible.
  • Document the “why” and not the “how”.
  • Update the documentation when the code is updated.
  • Make the documentation visible.

Focus on documentation tools

A variety of automation tools can be used to produce the documentation. Here are some open source examples:

  • Doxygen: produces documentation from annotations in the source code, stored in Git.
outils de documentation - doxygen
  • PlantUML: produces graphics from text files, stored in Git.
Outil de documentation as code : PlantUML
  • AsciiDoctor: produces PDF or HTML files from markdown files, stored in Git.
Documentation as Code : AsciiDoctor
  • PicklesDoc: produces a PDF or HTML file from BDD .features files, etc.
Documentation as Code : PicklesDoc
  • JUnit Viewer and Allure: these produce test documentation (test reports).
  • SonarQube: produces documentation on static analysis (e.g. analysis reports).

As you can see, the list is practically endless.

5. In conclusion…

As we have just seen in this article, much of the documentation is already available: all you need to do is find and centralise it. For the rest, it is possible to simplify documentation generation and automate its production: this is the example I gave with the software company in a highly regulated field. While the weight of documentation tasks became overwhelming and demotivated the team, automating specific documentation made it possible to reorganise work, improve team morale and, finally, simplify documentation work: a significant gain in time and efficiency!

Bruno Delb

Bruno Delb

DevOps coach at Wemanity, Bruno Delb has developed a passion for blockchains but also for soft skills. Former developer, he now has certifications in the field of Clouds.

Related posts

Balance between woman hands
Tech and Digital

How Important Is an Ethics Framework for a Better Data Usage by Entreprises?

Entreprises put data at the heart of their strategies and this place is more and more important in the daily...

3 days ago
Data and Entreprises: How Being Data-Driven Can Lead to More Agility
Tech and Digital

Data and Entreprises: How Being Data-Driven Can Lead to More Agility

The amount of data production will globally increase sixfold between 2018 and 2025. However, few are entreprises which use their...

1 month ago
Can My IT Architecture Be Eco-Friendly
Tech and Digital

Can My IT Architecture Be Eco-Friendly?

Did you know developers could adjust their code to take part in the global effort to reduce the carbon footprint?...

2 months ago
SEO redesign
Tech and Digital

SEO Redesign: Checklist and Experts’ Advices to Make Your Website a Success

Search Engine Optimisation (SEO) is too often considered as a side goal in redesigns. However, SEO can turn out to...

3 months ago

Recommended

Lean Canvas: Get Straight to the Point for Your Business Idea!

Lean Canvas: Get Straight to the Point for Your Business Idea!

December 8, 2021
Agile Transformation: Why Management Implication is Needed

Agile Transformation: Why Management Implication is Needed

May 5, 2020
Arie van Bennekum on 20 Years of Agile Manifesto: What Does the Future Hold?

Arie van Bennekum on 20 Years of Agile Manifesto: What Does the Future Hold?

February 11, 2021
How can you establish a culture of feedback in your organisation?

How to Establish a Feedback Culture in Your Organisation?

August 17, 2021

Categories

  • Agile Culture
  • Management and Organization
  • Tech and Digital
Powered by Wemanity logo

Categories

  • Agile Culture
  • Management and Organization
  • Tech and Digital

Join our community and receive our newsletter.

Rejoignez notre communauté et recevez nos dernières actus.

Sluit je aan bij onze community en verkrijg onze newsletter.

No result found
View all result
  • Agile Culture
    • Agile methodologies
    • Skills and expertises
    • Creativity and innovation
  • Management and Organization
    • Leadership
    • Work ethic
    • Team collaboration
  • Tech and Digital
    • DevOps and Craftsmanship
    • User experience and Digital Delivery
    • Data and Cybersecurity
  • EN
    • FR