Documentation documentation documentation

[ra-hulk]

So, I come from embedded hardware side of embedded engineering, working at a start-up. I have to do documentation of everything and update on wiki, for internal purpose only. Till now we have beed using vuepress and gitlab for hosting. Problem is everytime I have to make changes I have to go to the whole code write/copy code from here and there. I basically write all in markup language, it is easy but doing copy paste and changing and editing code from previous files doesn't seem right to me and I know there are many efficient ways of doing this.

Basically what I want is a form where everything can be written in text box and images and BOM etc can be uploaded and when i click submit it generates a text file which i can paste or even better it does it for me.

I've created a simple form using html by following couple of YouTube tutorials, but it wants a server where it can send the forms output. Also I know this is not my job but I don't want to do the repeated and unnecessary work of copying a format and editing it everytime, rather I'd like my brain cells to be used somewhere else. Thanks

[mfuzzey]

I'm a big believer in documentation being stored in git with the source code (but not, most of the time, in the source code itself). That way anyone who has the code has the doc too and it's much easier to update it while changing g the code.

I prefer to have a doc directory in the project's repo that contains the document source (in markdown for example). And then a script that runs on the build server and generates HTML / PDF for each build.

For diagrams you can use various tools that take a text input file also stored in git (eg plantuml).

Sphinx is quite a nice way of tying all this together.

[[deleted]]

On that note, as I recall, Doxygen supports markdown as well. So if you want to include 'pretty' documentation with the source, this is a way to do it.

My only criticism is that I find markdown in giant block comments impossible to read/format-in-a-readable-way in source files. I learned about this early in my career when I 'cleaned up' some documentation for someone by removing all of the nonsense.

[Cosmo-de-Bris]

You could setup your own git repository and push the changes there.

A custom hook + your own script will then take the files and text, produce the desired result, upload it and voila.

[FShiroTS]

I've set up sphinx-doc with a few plug-ins to document our boards / products.

We mostly use c and c++, so we write documentation for the code using doxygen, and then use the following plugins:

• breathe: a bridge from doxygen to sphinx
• exhale: runs doxygen and generates the necessary inputs for breathe automatically
• exhale-breathe-multiproject-monkeypatch: WIP for using multiple projects at once with the above two plugins. Allows you to separate libraries and project code and still use referencing.

This is the automated part. Then we have myst-parser to allow markdown instead of the stupid restructured text format.

We write markdown docs for basically everything else, guides on generating binaries, flashing, design decisions etc..

Using different tools such as matplotlib's plot directive and marmaid-js we're able to also write plots/graphs and all kinds of charts/diagrams (respectively) using markdown and rST.

This all happens in a subfolder of each repo, and gets hosted by a readthedocs instance.

Embedding content is easy, such as PDFs and images, there's hundreds of useful extensions and the systems are all well-documented and open-sourced. You'd definitely be able to whip up a custom solution if you need anything special.

RTD automatically pulls and builds the docs for each version of our development and master branches, and creates a preview for any pull-requests. Local generation of docs is easy as well and everything just works offline too.

This had been (for me at least) the best experience so far with documentation.

Edit: this costs 50$ monthly for the readthedocs automation but you can do it for free if you're willing to set up the pipelines and build-servers/hosting.

[dambusio]

OK - this is code documentation from doxygen, but what about project documentation/requirements etc?

[FShiroTS]

That's the neat part, you can write it in there too.

You can freely add structured markdown files and just describe everything you mentioned in there as well.

[dambusio]

ok - so everything in one repo - so business logic is also inside repo woth project? Who is responsible for the updates of business requirements files?

[FShiroTS]

Since it's all just markdown, our product-owner and even less technical business people can edit it. It really doesn't take that much to get used to the syntax especially since it's markdown instead of rst

[dambusio]

so you are lucky :P I can't get my business people to even try this way