[xtracto]

One of the things I recommend to the startups I advise is to include documentation within the repository. I always try to have a /doc directory which includes Markdown (I like using [1] self rendering markdown pages) and MermaidJS (For which I also created a dumb self rendering script [2]).

That way Merge Requests can be blocked for lack of documentation, or lack of documentation update.

MermaidJS have been a godsend for documentation.

[1] https://github.com/jcbhmr/ezmdpage

[2] https://github.com/obaqueiro/mermaid-js-auto-renderer

[Chris_Newton]

One of the things I recommend to the startups I advise is to include documentation within the repository.

Agreed, this can help. I sometimes wonder, having written a substantial project in literate programming¹ style once, whether that approach doesn’t deserve more exploration. Then not only is your documentation kept in the same repo as your code, your source files themselves almost become documentation first and code second.

You definitely have to do a lot of things quite differently to how we typically do them today to make that idea work well, but I suspect it could be like a good static type system, incurring a modest extra cost up-front but with a big long-term pay-off once you’ve figured out the tools and processes to take advantage of it.

¹ https://en.wikipedia.org/wiki/Literate_programming

[Hel5inki]

This is interesting, do you have an example repository with that setup? My team currently uses Swagger for documentation which provides decent documentation for us, so what sort of documentation at the repository level could I gain by using this setup instead or in combination? Also, how would one detect that the documentation has been correctly updated aside from manual inference?

[fijiaarone]

Swagger is not documentation, it is is a way to generate executable API examples from code comments.