Easily accessible documentation that is also easy to absorb is essential for a system developer. ”Easily accessible” means that the documentation must be available where needed or in a central searchable database. To be easy to absorb, the documentation should be well thought out and basic; think "what, how, and why" and then leave advanced parts for in-depth study.

Documentation is one of the developers' most important tools during the workday, for example, when developing a new function, during troubleshooting, or to provide correct support. If the documentation is well done and easily accessible, it can prevent support. Below are two examples where the developer's job becomes easier with the help of good documentation.

Documenting to help

In the first example, the task is to create an integration between two systems so they can communicate. For it to function without friction, rules are needed for how the systems must communicate. The rules must be documented, accessible, updated, and easy to adopt. Most of the time, the documentation only meets the first requirement, that it's documented.

A ”get started”-guide is an excellent way to start on, a "Hello world”* for everyone

A PDF of 120 pages of continuous text that takes a week to get through sounds like a good encyclopedia. But to get an idea of the project's complexity and what resources will be needed, it is better to have a simpler summary. Then, a "getting started guide" can be an excellent way to start. If the documentation is good from the beginning, it will also be easier to keep it updated and current. How extensive the documentation needs to be can vary; changing fonts in Word, for example, is something that most people know and, therefore, doesn't need to be documented in detail. But in order for the technology to be adopted on a broad front without bad implementations, for example, your macro going wrong, you need easily accessible and clear documentation on more advanced functions. Otherwise, the user may get stuck, get frustrated, and perhaps start looking for better-documented products.

[1] Macros i word

Here are some tips on how good documentation can look like:

• Make a get-started guide and summarise why, what and how. A ”Hello world[2]for everyone”
• Save the details for an advanced manual
• Aim
• Make documentation aimed at both your customers and your employees/colleagues
• Make it easily accessible (read more in this blog post)

[2] The ”Hello world”-chapter is often the first guide you see within programming when you start using a larger framework. The section contains the basics and only what you need to know to get started and get a first understanding of the framework. Based on that foundation, you can then continue to broaden 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 example, the task is to debug a function in a system. Documentation is needed so that the developer, in a simple and less time-consuming way, knows the purpose of all pieces of code. This type of documentation is usually found directly in the code. But, to get a better picture of the function, it is good to have documentation that explains the purpose of the function you are debugging. Why does the feature exist in the first place? What value does it deliver to the user? In this way, the developer can easily find out what the function should do, where it can go wrong, fix the error and check that the function works as it should. Documentation for this does not have a natural place in the source code. For a veteran in the organization, the purpose of the function may be obvious. However, we are not all veterans, and the documentation should be adapted for everyone.

If the purpose of the function can be linked to a place in the system where an end user uses it, the documentation should also be in the same place, directly in plain text or via a link. More detailed documentation may be available in a manual that describes more system features and details. Usually, these manuals exist but are then created from a customer perspective rather than as documentation for a developer. Give the creation of the manuals a little extra time so they also suit your employees. As a bonus, the customers can also access in-depth information if desired.

To Summarize

These were two more specific examples of a developer's everyday struggle for better documentation, but of course, there are many instances where it can make work more efficient. Newcomers to an organization often have many questions about what different parts of the job look like. What are the organization's procedures for case management, testing, code review and release? What happens when routines change? Or something as basic as: How do I 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 makes it searchable and available when needed also makes it easy to update.

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

• Is the documentation easily accessible for those who need it?
• Is it easy to understand?
• Do you keep it updated?

Want to learn more?