Executable Documentation Benefits
Katia A lot of software project documentations are outdated. Wouldn’t it be great if your documentation actually reflected the functionality in the system? One way to do this is to create executable documentation, also known as executable specifications.
Writing static documentation is useful, but dangerous, because it gets old and out of date as soon as the next person comes along, it should be constantly updated to be relevant all the time. For example, with a test-driven development (TDD) approach, part of the overall Agile Model Driven Development approach, your tests effectively become detailed specifications. Like it or not most programmers don’t read the written documentation for a system, instead they prefer to work with the code. When trying to understand a class or operation most programmers will first look for sample code that already invokes it. Well-written unit tests do exactly this – they provide a working specification of your functional code – and as a result unit tests effectively become a significant portion of technical documentation.
Similarly, acceptance tests can form an important part of your requirements documentation.
Tests are not sufficient for documentation, but they do form an important part of it. Requirements and tests are just two sides of the same coin. You can’t have a user story or requirement without an acceptance criteria (test). These two meld into executable specifications.
These specifications by example become “green” documents. Instead of having long spreadsheets of test cases with expected results, actual results and pass/fail, instead represent requirements as specifications by example and use them as automated tests. They help the team think and collaborate with the customer, and they communicate what the application really does. If the requirements change, the code will fail so there will be a need to fix the code. This way you get notified and your “documentation” is always updated.
Why software architects document their software projects?
1- Project stakeholders require it
2- Understand the trade-offs involved
3- Maintenance
4- Knowledge transfer & organizational memory
5- To think something through
6- Control
Documentation is an important part of agile software development projects. Understanding the need for balance is key as some organizations will place a higher value on certain documents than others. But nearly all should put more priority on creating a software architecture documentation. At Apiumhub we have an agile perspective on software documentation as we consider it as a strategy to contain project risks and therefore strive to be as efficient as possible.
Let’s have a look at the best practices from Agile Modeling for increasing the agility of documentation:
- Write Documentation
– Prefer executable specifications over static documents
– Document stable concepts, not speculative ideas
– Generate system documentation
- Simplify Documentation
– Keep documentation just simple enough, but not too simple
– Write the fewest documents with least overlap
– Put the information in the most appropriate place
– Display information publicly
- Determine What to Document
– Document with a purpose
– Focus on the needs of the actual customers(s) of the document
– The customer determines sufficiency
- Determine When to Document
– Iterate & repeat
– Find better ways to communicate
– Start with models you actually keep current
– Update only when it hurts
- Require Documentation
– Treat documentation like a requirement
– Require people to justify documentation requests
– Recognize that you need software documentation
Remember that a software architecture document is a map of the software. We use it to see, at a glance, how the software is structured. It helps you understand the modules and components without digging into the code. Consider it as a tool to communicate with developers about the software.
