Add user documentation

[robwa]

I suggest that we create user documentation together with Foodsoft and maintain it in a similar way to the tests. My feeling is that this should be

• be managed together with the Foodsoft code in the repository so that it matches the respective version,
• be created with a tool such as VitePress, which is made for this,
• be written primarily in English (and only translated if necessary), as this is the only way it can be maintained by all developers,
• be delivered with the deployment of Foodsoft, so that there can be direct links from Foodsoft to the documentation,
• be maintained and expanded in the same way as the tests are maintained and expanded when issues are worked on.

There are already some issues for which we could use such a system (e.g. #1106). Specifically, I see the need because I would like to maintain the documentation of the formats (e.g. the Foodsoft table format) outside the HTML forms when working on the import and export formats.

[lentschi]

Great idea 👍

[lentschi]

@mjavurek What do you think about this? Could we pull https://docs.foodcoops.net/de/home into https://github.com/foodcoops/foodsoft/tree/master/doc or is there an advantage in keeping it separate? (I don't know which technology is being used in https://docs.foodcoops.net/de/home, but @twothreenine indicated you might...?)

[mjavurek]

The technology used in https://docs.foodcoops.net/de/home is a https://js.wiki/
The content is stored in MD syntax and "mirrored" to https://github.com/foodcoops/user-docs, see https://docs.foodcoops.net/de/documentation/development/howtowrite#wiki-js
It is obviously an incremental backup and should be cleaned because there were several changes in the hierarchical structure during the writing process of the documentation and the (now abandoned) folders and files used before these changes are still there. Pages can be displayed on github due to the MD syntax, even embedded graphics are shown, but links to internal pages do not work on github.
@mariandl was involved in the setup and should know more about it.

[lentschi]

The technology used in https://docs.foodcoops.net/de/home is a https://js.wiki/ The content is stored in MD syntax and "mirrored" to https://github.com/foodcoops/user-docs, see https://docs.foodcoops.net/de/documentation/development/howtowrite#wiki-js It is obviously an incremental backup and should be cleaned because there were several changes in the hierarchical structure during the writing process of the documentation and the (now abandoned) folders and files used before these changes are still there. Pages can be displayed on github due to the MD syntax, even embedded graphics are shown, but links to internal pages do not work on github. @mariandl was involved in the setup and should know more about it.

Ah, great - thanks for the info!

So we could in theory to put it very shortly

1. move the generated sources from https://github.com/foodcoops/user-docs to foodsoft/doc,
2. set up vitepress in the foodsoft repo adding a CI pipeline to build foodsoft/doc and push the resulting HTML to be hosted somewhere and lastly
3. remove https://docs.foodcoops.net/de/home and https://github.com/foodcoops/user-docs

Loosely related note: There seem to be no English docs there - see https://docs.foodcoops.net/en/home