InfoCaption
Book a demo!

Good Documentation Makes System Development More Effective

Easily accessible documentation that is easy to handle is important in making the work that system developers do effective. Easily accessible means that the documentation should be where it is needed or in a central, searchable database. For the documentation to be easily accessible it should be planned and at first glance be fundamental, think ”why, what and how” to later come back and deepen more advanced parts.

Documentation is one of the developers most important aids during their work. As a developer, I document and need documentation when, for example, I develop a new function that will be used by a lot of users. I am also in need of documentation when I am troubleshooting a function to see what is wrong or to be able to give good and correct support. I have two examples of cases when I, as a developer, my job gets easier due to good documentation.

 

Documenting to Help

In the first case, the task is to create an integration with another system so the two systems can communicate. In order for it to go smoothly, rules are needed for how the systems should communicate with each other. The rules need to be documented, available, up-to-date and easy to access. Usually, the documentation only does the first thing; existing, that is.

A ”get started”-guide is a great way to start on…
…”Hello world”* for everyone

A 120-page PDF of text that takes a week of large doses of coffee to get through and understand sounds like a good reference. But in order to get a more general idea of the complexity of the project and the resources needed, it is necessary to provide a simpler summary. A "get started" guide is a great way to start. If the documentation is at a good level from the get-go, it also becomes easier to update and keep up to date. Easy and easily accessible documentation becomes more common as technical parts become more and more abstract. For example, changing typefaces in Word is something most people know and therefore need not be documented in detail. To make macros in Word[1] on the other hand, not as well known and needs good documentation. In order for the technology to be adopted on a wide front without bad implementations, such as your macro malfunctioning, easy-access and clear documentation is required for these more advanced features. Otherwise, users can get stuck, get frustrated, and perhaps more likely to find products that are better documented.

[1] Macros i word

A digital handbook about a web platform.

A few tips on what good documentation may look like:

  • Make a get get started guide, think: summarise why, what and how,, ”Hello world[2]for everyone”
  • Save the details in a handbook on an advanced level
  • Aim the documentation toward your customers and employees/colleges
  • Make it easily accessedle (read more in this blog post)

[2] The Hello world”-chapteris often the first guide you see within programming when you are going to start using a larger framework. The chapters are basic and only contain what you need to know to get started and get a primary understanding for the framework. From this foundation you can continue to widen your knowledge. Example: www.mkyong.com/html/html-tutorial-hello-world/. Example to make a step-by-step guide in InfoCaption.

 

Accessible Documentation With a Meaning

In the second case, the task is to troubleshoot a function in a system. This requires documentation that a developer, in a simple and less time-consuming way, should know what purpose all the pieces of code have. This type of documentation usually appears directly in the code. It's good, but to get a better picture, it's good to have documentation that tells us what the function that is being troubleshooted’s purpose is in the system. Why does this feature exist? What value is it to the user? In this way, the developer can easily find out what the function should do, where they may go wrong, fix the error and check that the function is working properly. Documentation for this does not have a natural place in the source code and for a veteran in the organization, it may be obvious what the function’s purpose in the system is, but not all of us are veterans.

A few lines of programming code.

If the purpose of the feature can be clearly linked to a location in the system where it is used by an end user, it should also be in the same place, directly in plain text or via a link. More detailed documentation can be added to a manual instead, that describes several features of the system and more detailed details. These manuals are usually found but are created from a customer perspective than documentation for a developer. Take a few minutes extra and keep in mind that these are not only good for your customers but also for your employees. The bonus is that customers will also be able to gain access to deepening if desired.

 

To Summarize

These were two more specific parts of a developer's daily struggle for better documentation. There are even more cases where good documentation makes the daily work more effective for a system developer. Newcomers to the organization often have many ideas about how different parts of the work look. Issues such as: "What are organizational routines for task management, testing, code review and release?", "What happens when routines change?" Or something as basic as "How do I get started and access the code?”.

"The same guide has since been updated as the system has been developed and has been used several times by both me and several newcomers in the company"

Saving all documentation in a central database that is searchable and accessible when needed makes it easy to update. I remember when I started at InfoCaption, I got the assignment to change the video player in the system. In the task description there was also a guide linked that told me how to install the system and how the video player worked. A few hours later, I was ready to deliver my solution. The same guide has since been updated as the system has been developed and has been used several times by both me and several newcomers in the company. Recycling is something that is effective in system development and also in documentation.

In order for the documentation relevant to your work to be more accessible and useful, you can ask the organization these three questions:

  • Is the documentation easy to reach for those who need it?
  • Do you keep it updated?
  • Is it easy to take care of?
Contact

The Author

At the blog, we share inspiration and knowledge about digital learning and Performance Support, and inspiring cases from our customers.

Feel free to contact the author if you have questions or want to discuss the article.

Adam Eriksson InfoCaption

Adam Eriksson