For this blog entry I have elected to discuss documentation standards and the role it plays in software process management. For my source I have chosen “Documentation done right: A developer’s guide” by Brittany Ellich & Sam Browning, this article was published on the GitHub Blog. The article discusses why documentation is one of the most essential parts of any project, and explains several principles of effective documentation, such as keeping documentation concise and clear, while effectively structuring it to have easy long-term maintenance.
How it Connects?
One of the big topics covered in CS-348 is documentation standards, I found this articles really emphasizes that documentation should be clear and concise. Which I find is a clear connection to what this course stands for and the topics listed in the syllabus.
Documentation and Team Collaboration
The blog recommends that information is organized using headings, consistent formatting, while additionally using documentation templates to keep things consistent.
One of the major reasons that all of this matters is because when it comes to working on code for a team, having documentation that can teach a new member the code base is instrumental when it comes to long-term maintainability. The last thing you want in your code base is an undocumented function where the only person who understands what it does left 12 years ago.
Applying These Concepts to Enterprise Networking
Although the article specifically discusses the use case of documentation in software, I was able to apply it to another CS field which I am active in; that field being networking. When is comes to network administration, keeping documentation about Firewall or Switch/Router configurations is absolutely key. All of these systems require documentation to ensure that they can be maintained, and more importantly modified safely, quite often do configuration changes lead to unforeseen consequences when altering a system that has been working for years but without documented configurations.
Reflection
Before I read this article I also had the impression that documentation generally only had use cases in software projects. But, after the reading I realized how important it is in networking and any technical field which has large systems which must be maintained and administered. And in most cases the documentation is equally as important as the system itself.
As I continue building my knowledge in these topics I anticipate that documentation will become increasingly important. Its one thing to build a large complex system, but being able to understanding it enough to write a concise and clear documentation speaks volumes about your understanding of the topic, and it ensures the continued operation and maintenance of that system.
Leave a Reply