How should we document Wakaama

[LukasWoodtli]

The Wakaama project needs documentation. There has already been some discussion about that in #729.

We should come to a conclusion about:

• What do we want to document
  • Code
  • Examples/Tutorials
  • Technical details
• Where do we want to put our documentation
  • repo
  • Wakaama Web Page
  • GitHub page
• What technology/markup language are we going to use for documentation
  • Markup language: Markdown, reStructuredText, asciidoc, ...
  • Documentation generator: Sphinx, static site generators, ...
  • Code/API documentation tool: Doxygen

[sbernard31]

I resume my opinion from #729 discussion.

1. I strongly advice to put documentation in code repository,
2. I strongly advice to use Markup language supported by Github,
3. No urgency to use tooling to generate static web site, Github rendering is largely enough in first time. (better to focus on code and documentation content)

This is just advises, so up to active committers to decide 🙂 .

[sbernard31]

@LukasWoodtli what you call GitHub page is Github Wiki ?
(Not directly linked bu there is already very few page in Wakaama wiki. )

[LukasWoodtli]

@LukasWoodtli what you call GitHub page is Github Wiki ? (Not directly linked bu there is already very few page in Wakaama wiki. )

No GitHub has web server functionality for project pages: About GitHub Pages

This is a convenient way to provide information about a project hosted on GitHub.

[LukasWoodtli]

I resume my opinion from #729 discussion.

1. I strongly advice to put documentation in code repository,

2. I strongly advice to use Markup language supported by Github,

3. No urgency to use tooling to generate static web site, Github rendering is largely enough in first time. (better to focus on code and documentation content)

This is just advises, so up to active committers to decide 🙂 .

👍
Agree!

[LukasWoodtli]

So my preference would be:

• Use seStructuredText (or alternatively Markdown) as markup language.
• Put documentation into the Wakaama repository.

Eventually/later:

• Generate documentation page with Sphinx
• Publish documentation page on GitHub pages
• Document the code (public API) with Doxygen (industry standard) and also publish it on GithubPages

[boaks]

I didn't follow all details, but for "publish it on GithubPages" I would first ask the Eclipse Foundation.
It may be considered to be related to marketing or SEO and then I guess, using the Eclipse way (e.g. Californium Web-Pages wold be preferred by the Eclipse Foundation. Anyway, I don't know it, so asking the foundation, if that hasn't been already done, would be the best.

[sbernard31]

Not sure to get the benefits to use GithubPages instead of publishing on Wakaama website.
But if you really want to go that way later, I also recommend to ask to eclipse foundation if this is OK. (just to be sure)

About Wakaama website :

• the website : https://eclipse.dev/wakaama/
• the repo of the website : https://github.com/eclipse/wakaama-website

[LukasWoodtli]

I had the impression, that the Eclipse Wakaama website is more static and includes general information where the GitHub page would be updated by each merge to the master branch with the newest developer documentation.

But maybe we can just publish everything on the Eclipse page.

I would discuss this as soon as we have any documentation to publish.

[LukasWoodtli]

Conclusion:

• Use reStructuredText as markup language.
• Put documentation into the Wakaama repository.

Eventually/later:

• Generate documentation page with Sphinx.
• Publish documentation page on the Eclipse page.
• Document the code (public API) with Doxygen and also publish it on the Eclipse page