How to Improve Documentation in Software Development

How to Improve Documentation in Software Development

Documentation can be a real pain in the a... neck. If the software works, why should I waste time in documenting the work? No matter how annoying it may be, the harsh truth is that reliable and accessible documentation improves your team's overall performance in the long run.

From the company's perspective, an inadequate documentation is a problem. People change teams and projects, new developers are recruited, somebody leaves the company and so on. Thus, without proper documentation, developers will waste a lot of time in figuring out the work done by others.

So, what can we do to improve the level of documentation? A rule of thumb in about any aspect of life is that people tend to do something if it is made simple enough. To make writing documentation as pleasant as possible, the first thing you need to do is to evaluate the tools your team uses.

Less Tools, More Results

The first hindrance in documentation is that traditionally you have to do it in a dedicated documentation management tool. This results in a situation where you not only need to jump to another tool to write documentation but also need to search for the documents in a different place than where the actual work is done.

Obviously, it would be easier to consolidate all the essential software development tools to one platform, and store all of the relevant information on it, right? When you have your team's source codes, issues, and documentation in one place, your team can focus on delivering results.

Our duty in Deveo is to make software development as seamless as possible. And we know that documentation isn't always very pleasant. So, by adding a handy git-powered wiki tool among the software development tools in Deveo, we wanted to serve both the developers' and the companies' interests. This tutorial aims at demonstrating how easily you can access and write documentation in Deveo.

Finding the Needed Documentation in Deveo

In Deveo, all the relevant information and tools can be accessed under individual projects. All the projects, in which you are involved in, are displayed in your dashboard.

When you are given the access permission to a new project (or you have set up one by yourself), it will appear in your dashboard, allowing you to access its contents.

In the project, you'll find all the relevant data on the sidebar, including documentation in the wiki tool. In the wiki, you can search for the documentation you need by opening the scroll-down menu.

When the documentation is project based, finding the needed information is easy. E.g. if you are trying to find documentation on some common concept that appears in multiple different projects (such as server environments), without the project based approach you'll have a hard time figuring out which one of the documents is the one you are looking for.

Writing Documentation in Deveo

As was mentioned before, people are more keen on doing something, if it is made easy for them. In Deveo, you can add a new document by just clicking the Plus icon in the top right corner of any wiki page. This will open an editor page.

As you can see, Deveo's wiki supports commonly used Markdown formatting, so it is very intuitive and effective to use.

Adding attachments and pictures is also made very simple. If you click the attachment link, you can easily drag and drop the files you want to add to the wiki page.

Additionally, if you use the different header types properly, the wiki also creates a table of content automatically, as you can see from the picture below. This makes finding the right information even smoother.

Finally, Deveo stores the documentation automatically to a git repository. This is a handy feature because it allows you to clone the repository locally and edit with your preferred text editor, access the wiki's change history, and integrate tools that auto-generate documentation from code to the repository.

In Conclusion

At the end of the day, the level of documentation is a cultural matter. If proper documentation is a part of company's culture and values, developers are more likely to write documentation. However, if you want to make sure that the documentation doesn't burden you or your team too much, you need to choose the right tools.

Seamless software development.

Code management and collaboration platform with Git, Subversion, and Mercurial.

Sign up for free
comments powered by Disqus