Proper Documentation (Code and Design Documentation)

This Skill of High-Quality Documentation is a technical skill because it requires software engineering knowledge and expertise to build the required mental model for proper documentation.

It can also be classified as a knowledge-based skill because it requires some form of technical knowledge to an extent.

Some of the prerequisites that are expected of a software developer trying to document a software system includes the following:

• Proper knowledge of the basics of programming and a programming language; the knowledge of the basics of programming language helps a software maintainer to decipher the source code of a software system.
• Understanding the software engineering principle; separation of concerns (Separating documentation in terms of structure, content, and layout).
• Adequate Understanding of the difference between these artifacts: User Manual,design documentation, Process Documentation,Code Documentation etc.
• Sufficient knowledge of the domain for the software being documented
• Computational Thinking,the ability to think in a computational manner aids the understanding of the problem being solved and the solution provided by the software system.
• Proper knowledge of mind mapping as it helps to visualize compartmentalize information to be documented.

Software Development Processes usually produce some artifacts based on the phase in the process .For most of phases in the development process a form of documentation is usually produced.

As such the following knowledge areas are considered related to the documentation skill:

1. Software Requirements: In this knowledge area one of the artifacts produced is the requirements Documentation and this artifact requires the documentation skill.The software requirement specification document is used to communicate the objective and functionality of the system to the stakeholders.
2. Software Design:The major artifact produced in this knowledge area is the design documentation which includes information about all the major design decisions that were taken during the development of the software system and the rationale behind them, this documentation also requires the documentation skill as it adds to the mental model of the maintainer regarding the software system.
3. Software Construction:This knowledge area produces the source code with comments (for maintenance). This process of including proper comments in the source code,could also benefit from the proper documentation skill as such this knowledge area is included in the related software engineering areas.
4. Software Maintenance: This is one of the driving forces for this skill. Code and Design Documentation is considered important to maintainers of a software system because it makes information about the design decisions made by the programmers, architect of the software system, easily and readily available .Thus improving the mental model of the maintainers regarding the software system, which improves their understanding of the system ultimately making it easier to maintain the system.

The Significance of software documentation has been emphasized by numerous researchers over the years each explicitly explaining the reasons why software documentation should be considered important.

In( parnas,2011) The author stated that “The prime cause of the sorry “state of the art” in software development is our failure to produce good design documentation.” . He stated that the lack proper documentation during the development process is the cause of many errors and it reduces efficiency in a software product development and use .As such to ensure software systems of good quality and maintainable quality are developed, it is important for software developers to have good documentation skill alongside other soft skills and hard skills required for the job.

Also, In (Kipyegen & Korir, 2013) titled “Importance of software Documentation” the authors stated that “Documentation is an activity that needs to commence early in development and continue throughout the development lifecycle”. This implies that documentation is prevalent throughout all the phases of development in a proper development life cycle as such there is need for the documentation skill at every phase of the software development to ensure maintainability of the software and increase the probability of re-use, which increases the importance of the documentation skill.

Finally, over the years, it has been concluded by multiple researchers that good documentation is important for posterity sake, it increases the lifespan ultimately of the software system.

The major role for people with the skill is a technical writer(As a technical writer you can work alongside other members of a software development team ). However, according to (Raise Labs,2019) some other roles for people with this skill includes the following:

• Technical Communication Specialists.
• Content Developers.
• Manual Writers.
• Documentation Specialist.
• Policy Writers.

For this skill, the typical artifact produced by this skill is a form of Text Document(Design Document,JavaDoc Document,Process Documentation) which could be of the following extension types: txt,pdf, latex , HTML etc . Although video documentation has been suggested, it has not been readily accepted as there have been some issues about the accessibility of its information(Jakub, Why Video Documentation Isn't the Answer 2016).

Some related activities to proper documentation include the following:

• mind mapping of the document structure and layout
• Determining the level of abstraction for documentation.
• Defining the scope of the document.
• Visualizing the process.
• Ensuring the documentation is up to date.

For more information about Documentation Activities click here.

Some examples of software projects artifacts created using documentantion skill includes :

• The JavaDoc Documentation for the Spring FrameWork.
• The Design Document for Mozilla.

In Schools, most tertiary institutions have courses that study each of the phases in the software engineering life cycle in their software engineering programs. These courses introduce the artifact produced by that phase of the process. Documentations are artifacts produced at the end of some development process phases .

So, academia contributes to the knowledge of the documentation skill through courses in the programs and school projects for the experience. Schools also cultivate this skill by teaching about the importance of documentation through courses like software maintenance and refactoring.

In the industry, organizations mostly with high process maturity levels focus on providing employees with the necessary skills for optimal work so they provide opportunities for employees to learn through seminars and online classes. Also, the industry allows for gaining more knowledge of the skill through practice. These are the ways the industry and Academia cultivate documentation skills.

For most types of documentation such as design documentation and process documentation a simple word processing application ( Microsoft Word, Google Docs) will suffice.

For a more research inclined document or if the documentation requires scientific components LaTex is another tool for documenting that provides scientific features .

As regards Generating Documentation from source code some of the available technologies include: It is worth noting that these tools for generating documentation from source code require some form of annotation in the source code that is supported by these tools.

• Junit: THis is the documentation generator for the Java Programming Language.
• Doxygen : This can be used for generating documentation from C++ source code although it also supports other programming languages.
• Phpdocumentor:This can be used for generating documentation from PHP SourceCode.
• LiveEdu: This a tool that allows for video documentation of code(Garbade, 2016).

During the duration of this course and in my previous school classes, I have had the opportunity to gain more knowledge about what it entails to create high-quality documentation through research work online, industry peoples experience through blogs, readily accessible design documents, and school syllabus. I have also been privileged to practice my knowledge in various school projects.

• Kamthan, P. (2020, July). INTRODUCTION TO SOFTWARE ENGINEERING DOCUMENTATION. Retrieved 2020, from https://users.encs.concordia.ca/~kamthan/courses/soen-6011/se_documentation_introduction.pdf
• Parnas D.L. (2011) Precise Documentation: The Key to Better Software. In: Nanz S. (eds) The Future of Software Engineering. Springer, Berlin, Heidelberg.
• Kipyegen, N. J., & Korir, W. P. (2013). Importance of Software Documentation. IJCSI International Journal of Computer Science Issues, 10(5). doi:https://www.ijcsi.org/papers/IJCSI-10-5-1-223-228.pd
• Rachel, T. (2019, July 03). Why documentation matters, and why you should include it in your code. Retrieved July 26, 2020, from https://www.freecodecamp.org/news/why-documentation-matters-and-why-you-should-include-it-in-your-code-41ef62dd5c2f/
• Raise Labs, I. (n.d.). Technical Writers: Salary, career path, job outlook, education and more. Retrieved July 26, 2020, from https://www.raise.me/careers/media-and-communication/technical-writers
• J. (2016, July 26). Why Video Documentation Isn't the Answer. Retrieved August 07, 2020, from https://stormpath.com/blog/video-documentation-isnt-answer
• Garbade, D. J. (2016, August 15). 10 Tools for the Perfect Code Documentation. Retrieved August 08, 2020, from https://blog.education-ecosystem.com/code-documentation-tools/
• Hariharan, Sriram. 10 Most Popular Tools for Technical Writing. 25 June 2020, document360.io/blog/tools-for-technical-writing/.
• Souza, Sergio Cozzetti B. de, Anquetil, Nicolas, & Oliveira, Káthia M. de. (2006). Which documentation for software maintenance?. Journal of the Brazilian Computer Society, 12(3), 31-44. https://doi.org/10.1007/BF03194494
• Kothari, V. (2020, May 13). Software Requirement Documentation: Importance And Best Practices. Retrieved July 25, 2020, from https://www.movinnza.in/blog/software-requirement-documentation/