Put Your Documentation In Source Code

As I research various technologies and ways of doing things, one thing that I found is that people are putting their project documentation in with their source code. Now the documentation files are kept separate from the code files, but they are both within the same repository. Why would someone do that? I came up with the reasons below on why someone would put mix their documentation in with their source code.

Easier To Keep Documentation Up To Date

The main driver for this is that everything that you have associated with your application, website, or project, is in the same location.

This means that when the source code gets updated with new features or bug fixes, the
documentation can be updated at the same time to reflect the code changes instead of having to go to a separate system and make the documentation update.

As a developer, having to go to a different system or application to make updates to the documentation is a pain. Even worse when management requires the documetnation to be placed in a Word document for it to be stored on a Sharepoint site that after some amount of time, is abandoned or left for digitial dirt.

CI/CD for Documentation

Just like your application can be deployed to production using CI/CD, the documentation can be done in the same manner. In my opinion, the documentation is available online, either as part of the application or a separate website. By it being available online, it can also be deployed to production by a CI/CD process, similar to your source code.

This website is set up in a manner like documentation. When a change is made, it is then automatically deployed using Github Actions.

Repository Folder Structure

As I update my existing projects, I have decided to use the below folder structure for my projects. Now this structure may vary depending on what the project is for or if there are no files in some of the directories, but this is the general idea for doing this.

• documentation
• source
• systemd
• tests
• website
• README.md

documentation

I suggest doing documentation in Markdown. There are a number of tools and utilities that can process Markdown files into websites or other formats. Also because Markdown utilizes plain text files, you can see changes make to the documentation, as new versions of the application are released.

source

Source (or src) directory contains the source code for your application. If your application is divided into multiple projects, then all of those projects would be placed in this directory.

systemd

Some of the applications and automations that I have created run as system services on Linux. For those that are not familiar with system services, to create a system service, you have to create a service file that is used by the Systemd service.

Including these files in the repository, means that if something were to happen to the computer and the file need to be restored, that it could be pulled from the repo.

tests

All of the tests for the source code go into this directory. Now you can create separate folders for the different types of tests (e.g., Integration Tests, User Interface Tests).

website

This folder contains the website for the application, if applicable. Like the documentation, the website ewould need to be updated of new features when the application changes. Also like the documentation, updates made to the website can be done using CI/CD processes.

README.md

Readme file is the file that you see on Github when you initially look at a repository. In some projects, the README file is used as documentation for that project. Sometimes that is sufficient instead of using an entire directory, but when you have a lot of documentation, it is best to use the documentation directory instead of using the README file.

contribution.md

When you create open source projects, you need to have guidelines on how people can contribute or fix errors that they find with your project. Having file that outlines contribution steps, such as opening an issue on a repository or providing an email address of the person to contact are things to include in this file. This information could also be included in the README file as an alternative.

Conclusion

There may be some other folders or files that I may consider adding as a standard as time goes on. This set of folders covers the majority of things that are needed to organize code in a easy to understand manner and for those that are not familiar with your project to find what they need for your project.