git – Where to store the documentation and supporting files for the project?

Question:

Where to store documentation and auxiliary files that are not related to the code, for example, screenshots for README.md?

Based on the screenshots, I found two answers to enSO:

But it touches more on the issue of formatting README.md through Markdown. I'm interested in best practices for storing auxiliary data. Which storage location should you choose? Separate branch or repository? How to use this ancillary data?

So far, I see the following solution for myself. I create a branch with auxiliary data in the project and put screenshots there, and I already access them from the README.md file.

For documentation, the situation is similar; I think while the project is small, docks can be stored in one repository.

I myself am currently using GitLab / GitHub.

Please share your experience.

Answer:

It is better to keep the documentation (screenshots and diagrams refer to it) in the same branch as the code. For example, in a separate directory at the root of the project directory docs . The closer the documentation is to the code, the less likely there is a discrepancy between the code and the documentation.

For many frameworks and build systems, there are rules for storing documentation for the code. For example, maven expects you to have a site directory with documentation in it, so maven can format it and upload it to the site.

Also, many frameworks can throw errors if there is no documentation for the code.

There are various build system plugins that help you create, test, and publish documentation. For example, AsciiDoctor has plugins for various build systems.

Scroll to Top