John is a long time analyst in a large company, and is responsible for requirements elicitation in new and existing software products. Watch Now! Jane is a developer in the same company.
She usually receives from John the SRS to start making technical analysis and designing what is to be implemented. When this analysis is completed, she starts coding. No big up front requirements and design were to be made, specifications and developments were to be split in small chunks of information, and big word documents like the ones used for several years were to be discarded.
The way developers coded also changed, and things like designing tests before implementing, and naming functions with longer names were being encouraged. The adoption of agile methodologies in project management and software development has experienced a rapid growth in the last decade and is expected to keep growing.
In transitioning to the agile way of working, many Johns and Janes throughout the world pose the same questions on what appears to be such a loose approach to development and is definitively a different, less traditional way of doing things. In the middle of all the differences in the way companies begin to work when transitioning to the agile mindset are issues relating to documenting. This article focuses on why, when, how and where to produce technical and functional documentation.
Although it does refer to documentation, agile principles do not give any rigid guideline on how to document. Therefore, what is expected to be produced in terms of documentation in an agile managed project? The principles behind the agile mindset focus on delivering value to the customer. That means that the time we spend developing the product should be spent doing something that adds value to the customer, avoiding wasting time in tasks that add little to no value.
This also applies to documentation. In the typical waterfall approach, documentation is a predefined phase that consumes a lot of time. Transitioning to an agile approach means that we have to rethink the way we document, in order to avoid wasting time producing a deliverable with questionable value. Another of agile principles lies in adapting to change. That means that we do not plan too much in advance because things do change along the project.
So, the main focus is always in just-in-time planning. This applies also to documentation. In order to avoid wasting time, documentation in agile should occur only when it is necessary.
When coming from the Waterfall world, the natural tendency is to bring along habits of defining big requirements up front, which can lead to:. In order to avoid that, there are some guidelines to help us decide if we really need to document it. The key to deciding whether we should document or not is defining just-enough documentation. Find the balance between what stakeholders really need and produce exactly that.
No more, no less. Just enough. After agreeing on why and how much to document, define what documentation will be produced BEFORE you start producing it. Align with the target audience of the documentation what will be produced. Training documentation? Maintenance support documentation? Business rules documentation? System description documentation? In order to decide what to document, define what technical and what functional information will be produced, in each phase of the project:.
There are, in fact, situations in which documentation is absolutely required. Adding user stories to the backlog, creating flowcharts, drafting wireframes, documenting client meetings — Agile simply suggests being smart about it.
Too much or overly comprehensive documentation would be a waste of time, and developers rarely trust detailed documentation anyway because it's usually out of sync with the actual code. On the other hand, experience shows that too little documentation is always a source of problems with team communication , learning, and knowledge sharing. Either way, there are several valid reasons to invest time in it:. Your project stakeholders require it.
The creation of documentation is fundamentally a business decision, you are investing the resources of the project stakeholders in the development of the documentation, so they should have a say on whether their money is to be spent that way. To support communication with an external group. It isn't always possible to co-locate a development team and it isn't always possible to have project stakeholders available at all times. Shared documentation is often part of the solution in combination with occasional face-to-face discussions, teleconferencing, email, and collaborative tools.
To support organizational memory. That means that while you need to develop software, you also need to develop the supporting documentation required to use, operate, support, and maintain it over time.
For audit purposes. Depending on the type of system you are developing, it might fall under certain audit guidelines. In that case, you would need to follow a defined process and capture proof that you did so, resulting in more documentation. However, if you really dig into what compliance requires, lightweight documentation usually works just fine.
To think something through. The act of putting ideas down on paper can help you solidify them and discover problems with your thinking. What appears clear and straightforward in your mind can often prove to be very complicated once you attempt to describe it in detail, and you can often benefit from writing it down first. While all of the above may be legitimate reasons to document, we always ask ourselves the question: What's the least amount of deliverable that we need right now?
To make the most of the time we invest in documentation, we follow a few simple rules:. Keep in mind that any document you create you will have to maintain later on. If the documentation is light, uncomplicated, and not too detailed, it will be easier to comprehend and update. Wait before documenting — it's the best way to avoid accumulating false and outdated information. Produce documentation when it is needed, not before. Keep it in one place and make it accessible.
If documentation is only useful if it's accessible. Store your product documentation in a place where you and your team members can easily find it. Collaborate with your team. Maintaining documentation in Agile teams is a collaborative process, and every team member should be encouraged to contribute. To make all of the above possible, a flexible, transparent, and easily accessible software documentation tools is needed.
Unable to find a solution that would tick all the right boxes, a few years ago our team decided to scratch our own itch and build a better tool ourselves. Bullet charts will do. If necessary, you can follow up with them for additional information. Also, any operational notes, such as the discovery that the software now requires specific hypervisor settings, must be included. This lets me neatly segue to:.
This individual collects the information from the engineers and merges it into a cohesive document. Ideally, this should be a tech writer who understands the issues involved in getting content written and who can manage document version control.
At the start of the project, this person would also pick the writing tools, such as Microsoft Word or a DITA editor, and what documents need to be written.
This person should be dedicated to this task and this task alone. See point one. There are many reasons for this requirement. A tech writer with an engineering background can talk shop with the software engineers and get the key points without requiring someone to explain in detail to the writer what is going on.
An engineer can readily learn—if they don't already know—the technologies the project uses. If the writer has programming experience, all the better, because they can be given source code to study and can concoct any sample code. One of agile's strengths is that the regular scrums give every team member a clear picture of what's going on over the entire project. This can give the tech writer an idea of what software modules have stabilized and therefore where to commit their efforts on the next sprint.
In addition, since many complex software systems consist of black boxes communicating with one another, the tech writer can use this big picture to produce an overview document that explains the interfaces and data flows, which will be valuable to the operations team. There's little reason not to integrate the documentation effort as part of an agile process.
Like any other software project, the key is to commit the resources to the effort. Because the tech writers are working closely with the developers and QA testers to collect information, these people should be engineers themselves. That might seem like the most daunting task of all: finding an engineer who's both knowledgeable in the field and enjoys writing.
They're out there, and they should be members of every agile project. Take a deep dive into the state of quality with TechBeacon's Guide. Plus: Download the free World Quality Report Put performance engineering into practice with these top 10 performance engineering techniques that work.
Discover best practices for reducing software defects with TechBeacon's Guide. Skip to main content. Our Contributors About Subscribe. Waterfall documentation makes your job harder Under the waterfall technique, the development team has little reason to care about documentation.
Writing documentation the agile way Taking a more agile approach to documentation can solve all these problems.
0コメント