Documentation

[drbacke]

I think WE should start with a better documentation.
Any suggestions on how WE should do this?
Wiki, readme, API doc ...

[sandboxcode]

We document all internal repos and projects with a single Nextra repo within our working groups Github organization (though it is private and I can't share it at this moment).

Great tool and if we want to use it, please open another repo and call it something like EOS-docs.
It makes it way easier to maintain.

[fortrieb]

Currently we can stick to README and if we have enough content to start a website then can starting with github pages.

[BerndCzech]

Is there a reason to keep the README-DE.md? Imo its duplication leading to confusion and increased effort with limited value.

I would offer to:

• check for inconsistencies
• merge all into README.md
• delete README-DE.md
  ok?

[fortrieb]

I think translation of documentation make a lot of sense, to attract more users later. Currently project isn't at this state to be used by none developers. Should be ok to delete the german readme file.

[b0661]

What about Sphinx and/or Doxygen to extract documentation from source code and also add pure documentation files. The tools are used by many open source projects and can generate HTML and a lot of other formats. It´s also easy to upload the documentation to Read the Docs, which spares an own documentation server, provides good visibility and is free for open source projects.

Both tools ( Sphinx, Doxygen ) support API documentation extraction from source code and enable to write documentation in Markdown or reStructuredText (reST). Using such a simplified markup language for documentation enables to easily handle the documentation files in git with the same handling like source code files.

[fortrieb]

Extracting comments from source files isn't enough to get started with this project. Some tutorials would be helpful to get started by normal users if project reached a usable state.

[drbacke]

Yes If we have a First docker Release + swagger (usefull API documentation).
This could be the start for the next step

[mattmeye]

Just another hint from a developer: Mkdocs Material, can also be easily integrated in github actions
https://squidfunk.github.io/mkdocs-material/publishing-your-site/?h=github#with-github-actions

[TheSmartGerman]

In my opinion documentation should be made easy accessible.

Using/Enable the GitHub Wiki and make it editable for everyone. So everyone can contribute.

Try to start with a good structure....

e.g. I started this wiki (my part of contributing to this project) and it's growing since: https://github.com/open3e/open3e/wiki

[mattmeye]

I completely agree with you. The focus should be on documentation (preferably in Markdown) and you shouldn't get bogged down in visualization/publication.

As I said, I often use mkdocs material both privately and professionally with large development teams. You define where the documents are located, where the generated documentation should be located, and that's it. In my opinion, the biggest feature is the search across all documents.

[mattmeye]

I played a little bit https://mattmeye.github.io/EOS/welcome/ and just found out that it exists also a sphinx variant https://jbms.github.io/sphinx-immaterial/index.html