1

I am looking for a recommendation on what solution is a good practice for documenting and updating an application using a git repository.

We are working with a large codebase and multiple teams of developers, while feature documentation for end-users is done by one person, something I intend to change, as no single person can keep up with the amount of changes coming in. The idea is letting multiple people constantly update the repository. An option is, when anyone completes a feature or any significant change to the application (from the user's point of view), they should create a respective entry in the documentation repository.

Currently the favorite solution is to use LaTeX and put everything in a GitLab repository, however some developers favor "something markdown-based" over TeX, so I am here to ask if there are well known industry standards in terms of solutions for this.

TL;DR:

What software could be used effectively to achieve placing documentation in a git repository to be updated constantly by multiple people, when they each complete features? Is there an industry standard?

|improve this question
  • 1
    Regarding the User documentation did you have a look at e.g. Serna and the docbook format. Regarding the repository I think a type git repository is the preferred solution. A bit out of curiosity, what are you using for documenting the code / in which programming language is the application written. – albert Oct 22 '18 at 9:35
  • 1
    as you are already using gitlab and prefer "something markdown-based", why you don't use gitlabs markdown? – DJCrashdummy Oct 22 '18 at 9:42
  • 1
    Adding to that, Github as well as GitLab have a "Wiki" section for each project. If GitLab does that the same as Github (which I guess), that's basically a separate Git repo you can deal with as with any other: pull, edit, push. Which means: you can edit online or offline, as you wish. And use your favorite Markdown editor offline. – Izzy♦ Oct 22 '18 at 10:25
  • The end result can be e.g. a manual for users to learn what features do and how to use them. So the end result is supposedly a PDF file which is the case already, it's just that getting to that PDF file and keeeping it updated is currently done horribly inefficiently. – Mär Oct 22 '18 at 10:32
  • 1
    I think documenting code by means of Office products is not the best choice (discrepancy between source / implementation and documentation). I would choose a program like doxygen for documenting the code. – albert Oct 22 '18 at 10:35

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Browse other questions tagged or ask your own question.