Documentation is an important part of any project and it is crucial that it is written in a clear and reliable way. In this project we analyse different types of documentation and the style they are written in. The goal of this project is to create a perfect documentation style that best fits modern documentation ways.
In the modern business world, projects have been growing significantly in size and keeping track of them has become more important than ever, especially since complex technology has become involved. Documentation solves this problem. It has a single purpose - to keep all of the available information about the project in a nicely presentable fashion. When a new person joins the project, they should be able to get fully acknowledged with it simply by reading the documentation. At the very least they should be able to start working as a productive member of the team simply by reading the documentation.
(TODO: we need to write a good static description of Working information here)
Without documentation all of the project's information is stored in the heads of the people involved. We can call this working information or working knowlegde.. This information is really stored in brains and therefore is most useful and can be applied and used at any time. Every person working on the project should have as much working information as possible. We can safely say that more working information should generally make for a better project worker (this is only one factor on which we can measure employee quality). A the end of the day, it is beneficial for the project that every person working on this project has as much working information as possible.
Unfortunatelly, working information is hard to come by. A person must:
These sources of obtaining working information are listed in order of difficulty. The first option is the easiest. It is very simple to get information from someone ("guide") explaining it and talking the new people through every aspect of the project. Unfortunatelly, this requires the guide to take time off to explain the working information to the new person, the time they could have spent working on the project instead. In large projects this can take several weeks, which is unfavorable from a business side. Additionally, this way of sharing the working information has normally only one person ("receiver") who obrains the new information (there can be more receivers at once). At a later time, when another new person comes to the project, the whole process needs to be repeated from start.
Documentation is a a hassle to write. This second option of sharing the working information requires guides to spend extra time. Unlike the first option, the result here is not immediatelly visible and it usually takes longer than explaining the information to a single person. This is why this option is not so popular amongst project workers. On the long run, however, this option saves a lot of time, since the documentation has to be written only once. It has become a common practice in bigger companies to set aside time to write documentation for each project.
The first option provides results immediatelly, however it is one time use only. It additionally degrades over time, since people tend to forget such information when not activelly working on a project anymore. The third option is the worst, since every person needs to go through the raw project and create their working information from scratch. The second option is the most optimal for long term information keeping. In this project we will focus exclusivelly on this option and analyse various types of documentaiton.
There are many various types and styles of documentation and they each serve and acomplish a different goal. In this project we will analyse each of them separatelly and try to describe the best one for each situation.
I have been working on many projects with various degrees of documentation. On projects that have been lacking documentation, I had serious trouble to generate working knowledge of the project, since I had to talk to project personell, most of which were too busy to talk to me about the project and some of which were off the project for soo long that they no longer were able to sucessfully recal their working information. On the projects that had written documentation another problem arose. I was unable to easily find the information that I required. Therefore, in this project I will analyse different types of documentaiton, their benefits and shortcommings, and aim to determine where they are most useful.
There is already a lot of research done about informaion, both mental and digital or wiritten. We explore this research in detail here.
As we have written in the Introduction, we defind the term Working Knowledge as detailed personal knowledge about a particular project. A person working on a project obtains working knowledge through various forms of learning (see above).
How fast a person is able to accumulate the project's working knowledge is defined by this person's Information literacy. The higher the information literacy of a person, the faster this person is able to obtain or create working knowldge of any project.
"Information literacy is a set of abilities requiring individuals to 'recognize when information is needed and have the ability to locate, evaluate, and use effectively the needed information.'"
(src: https://libguides.madisoncollege.edu/InfoLitStudents)
Documentation of a project is split into:
This documentation split is made based on the purpose the documentation holds within the project.
Projects grow in size quickly. Project documentation is the basic documentation about projects.
Since the early days of programming, the code has been slowly evolving more and more in favor of human readability. Our projects have been growing in size and the development teams are bigger than ever. Since so many people are working on a single project the need to communicate and to communicate well has also grown significantly. In software development, one of the main points of this communication is What the code does and How does it do it.
Code documentation does not have a single purpose, but instead attempts to answer a few questions at once:
Publishing mostly deals with Articles.