It's been quite some time since I wrote the last article in this DevOps series. But it's time I focused on one of the most crucial essentials in DevOps, which is documentation.
It might feel like a very obvious activity within the DevOps community, but efficient documentation is often neglected across different organizations.
There were brief attempts to create a Continuous Documentation methodology. There was also a movement to create a DocOps Framework that came out of CA (now Broadcom). Despite its initial promise, DocOps never caught on as an industry movement.
Before I dive into it further, it is essential that I briefly talk about Black Box Testing and White Box Testing.
Black Box Testing
Black Box Testing corresponds to the non-functional aspect of a software. It has nothing to do with how the software works and focuses on the usability aspect of the software. To be able to do a Black Box test, you only need to be an end user.
Why is such an approach referred to as a Black Box? Black denotes opaqueness, which indicates that you only have user-level access to the software and cannot look into how it works internally. Know-how of source code in such a case is irrelevant.
For example, to do a Black Box test of Firefox Nightly, all you have to do is visit the Firefox Nightly Download Page, download, install and run the browser.
Another name for this type of testing is Behavioral Testing, because it is all about how the software “behaves” in real-time.
White Box Testing
White Box Testing corresponds to the functional aspect of a software. It is all about how the software works and focuses on the development aspect of the software.
To be able to do a White Box test, you need to take the developer's path. Why is such an approach referred to as a White Box? White denotes transparency, which indicates that you have developer-level access to the software and can look into how it internally works. Know-how of source code in such a case is essential.
For example, to do a White Box test of Firefox Nightly, the best place to start is the Firefox Source Docs and also perhaps the Firefox ASan Nightly Page.
Another name for this type of testing is Code-based Testing, because it is all about how the software gets “coded” and built in real-time.
What is Documentation Testing?
Documentation Testing is a validation procedure of the documentation towards testing the functionality, usability, and security of any systemic process under development. It makes sure a system works exactly as documented.
What is DocOps?
On the lines of how DevOps works, DocOps is a continuous simplification process that speeds up Documentation Testing with careful efficiency.
Conventionally, Documentation Testing has always been regarded as a non-functional form of Black Box Testing. But in the current era, that cannot just end there, and DocOps needs a desperate comeback.
Documentation Testing can go beyond the limits of the Black Box because knowing the procedure to develop, build or even deploy a software can also be an essential factor in mitigating bugs and fixing issues.
That, also, requires careful documentation as described in the Firefox Source Docs(linked in the previous section as an example). Therefore, Documentation Testing can involve both Black Box and White Box Testing altogether. So, if you must undertake such a validation procedure, you must do it at three levels:
- Functionality Documentation Testing
- Usability Documentation Testing
- Security Documentation Testing
Functionality Documentation Testing
Functionality Documentation Testing is a White Box approach towards the system. It validates the documentation created for developing, building and deploying the software.
Usability Documentation Testing
Usability Documentation Testing is a Black Box approach towards the system. It validates the documentation created for downloading, installing and using the software.
Security Documentation Testing
Security Documentation Testing is both a Black Box and White Box approach towards a system. It validates the documentation created for conducting penetration testing and ensuring optimum security of the software and its system.
Documentation Improvement Life Cycle (DILC)
The effectiveness of functionality, usability, and security testing depends upon the simplicity of documentation for each phase of a system's development. If you look at the process of documentation as a systemic process, it can adopt the same System Development Life Cycle model I'd designed and presented earlier:
If you only focus on the above diagram with respect to documenting how to perform each of the labeled tasks, it would then collectively become a Documentation Improvement Life Cycle that would continuously enhance the quality of the complete manual. As software development begins, its documentation would also go through continuous revisions based on what works and what doesn't, however big or small.
It is unfortunate that DocOps isn't being much explored in recent times. Software, on its own, might be excellent, but it can be rendered completely unusable without proper & precise documentation. This is where Documentation Testing comes into play, and so carries an equally important role throughout software lifetime. Therefore, software on its own will always be as excellent as its documentation, and that is the essential truth.
When you have better documentation, you obviously end up with lesser/closed issues on GitHub or any other repository provider.
On the lines of what I just discussed, our primary goal at Linux Handbook is to explore both Functionality and Security Documentation Testing because the focus is primarily on documenting the server side of Linux. It's FOSS, on the other hand, relates to Usability Documentation Testing because of the primary focus on Linux user-experience, ease of use and simplicity.
Documentation Improvement Life Cycle can also be related to our continuous attempt to keep our articles up to date and ensure everything covered earlier can still be tested and works as is, which is a key requirement of Effective DocOps.
I hope you found this reading useful about why continuous documentation can be a forever goal. I'll be exploring the DevOps series further on and explore HumanOps in my next article(in this series). If you have any suggestions and thoughts to share relevant to this series or this article in particular, please let me know in the section below.