Testing is Documentation

Documentation needs to be comprehensive, updated in real time, and understandable. When I say comprehensive, I mean that in addition to introducing the functions of the program, it should also cover some important places in the code. The importance of documentation is self-evident to many people, but it is difficult to keep it up to date and accurate. The consequences of poor documentation are often more wasted resources and time. Documentation is often written for the wrong reasons.

Some Reasons to Ask for Documentation

There are many reasons why we need to write documentation. Teams often write documentation due to some institutional requirement, or simply out of sheer ignorance. Here are some reasons why documentation is wrong:

- Some people think that documentation is closely related to the success or failure of a project.
- Documents that can prove the existence of certain people.
- The demander doesn't know what to expect except documentation
- The person who asks you to provide documentation is asking for peace of mind, knowing that everything is OK
- Workflow prompts that you should create documentation

Documentation

is a major part of outdated software documentation The problem is that it's usually not up to date. Some part of the code may have changed, but the documentation doesn't reflect that. This sentence applies to almost all documents, but the most influential ones are actually requirements and test cases. No matter how hard you try, the expiration of documents is inevitable.


Who is the documentation useful for?

Depending on the audience, the type and format of the document will vary accordingly. Developers, testers, clients, supervisors, end users are the biggest potential users of documentation.

Developers

Developers should not rely on documentation as they are often out of date. Beyond that, no documentation provides more detailed and up-to-date information than the code itself. If you want to know what a method does, take a look at this method. Not sure what a class does? Take a look at it. Usually only poorly written code needs to be documented.

Using the code itself as documentation doesn't mean you don't need additional documentation. The key is to avoid redundancy. If a look at the code gives details of the system, there may be some additional documentation to provide a quick introduction and a high level overview of the functionality. The documentation of the code itself cannot answer the question of what the system does or what technology is used in the system. In most cases, a simple README.md is enough for a developer to get started quickly. Things like project description, environment configuration, installation, build and packaging instructions are very useful for new members of the project. But after that, the code is your bible. The production code provides all the required details, while the test code serves as a description of the inner intent of the production code. Test cases are executable documents, and TDD (Test Driven Development) is the most common way to implement it.

Assuming you use some kind of continuous integration, if part of the test-documentation (in this case, the test is the document, and the document is also the test) is wrong, the use case will fail and it will be fixed quickly. Continuous integration solves the test-incorrect documentation problem, but it doesn't guarantee that all features are documented. For this reason (and of course other reasons) test-documentation should be created using TDD. If all functions are defined as test cases before code development, then test cases can serve as a complete and up-to-date documentation for developers.

What about the rest of the team? Testers, customers, supervisors, and other non-coders may not get the information they need from the production and tested code.


Testers

The two most common types of testing are black box testing and white box testing. This distinction is important because it also divides testers into two categories: those who know how to write code, at least those who can read it (white-box testing), and those who don’t understand code (black-box testing). ). Sometimes testers do both. But generally speaking, tests don't understand code, so documentation that is useful to developers is meaningless to them. Unit testing is not the right thing to do when it comes to stripping documentation from code. This is the value of BDD (Behavior Driven Development). It gives non-developers the documentation they need, but also has the benefits of TDD and automation.

Customers

Customers need to be able to add new functionality to the system, and at the same time they need access to important information about the current system. The documentation given to them must not be too technical (of course the code is not) and must be up to date. Behavior Driven Development (BDD) stories and scenarios are probably the best way to provide this kind of documentation. It can be used as acceptance criteria (before code development), it can be executed iteratively, and it can be written in natural language, which makes BDD not only able to keep the documentation up-to-date, but also for those who don't want to see the code. very useful.

Executable Documentation

Documentation is an integral part of the software. Like the rest of the software, it has to be tested frequently to ensure it is accurate and up-to-date. The most efficient way to achieve this is to integrate this executable document into your continuous integration system. TDD is the obvious choice in this direction. At a low level, unit tests are a good fit for this documentation. On the other hand, at the functional level BDD is a good way to use natural language to describe, which ensures the readability of the document.

Please indicate the source of original article reprint: http://it.deepinmind.com

English original link