Extend documentation for 1.0 release and website

[MatthiasKillat]

Documentation epic

Proposed outline

• index.md
• What is Eclipse iceoryx? (Explain the three pillars easy, safe, fast)
• getting-started
  • overview.md (Split?)
    • General intro (add overview pictures e.g. from ROSCon slides, add section "limitations")
    • hello world/quick start: icedelivery c++ typed (without and_then?) icehello
    • User API (Move into examples)
      • Typed
      • Untyped
  • installation.md (move colcon to advanced?, usual user just wants to use script and nothing more, link contributor installation guide, move iceoryx_posh options table to advanced, fix markdown no identation before code blocks)
  • examples (overview over examples)
    • Communication with polling for the user /for frameworks
    • Options
    • Listner
    • Communication without polling
    • Debugging (iceperf, icecrystal)
• API-reference
• (API-cheatsheet.md)
• FAQ.md
• advanced
  • Contriubtor guides
    • best-practice-for-testing.md
    • Modern C++ error handling (Optional, expected)
    • installation-guide-for-contributors.md
  • iceoryx_utils.md
  • usage-guide.md

Documents covering

• Extend installation guide
  • QNX7 with QCC 5.4.0
• Introduction: motivation, goals and capabilities of iceoryx
  • Which data types are allowed to be sent via iceoryx? What are the limitations (virtual, vtable, heap)?
  • Clarify failure cases, e.g.
    • What happens if an application segfaults? If crashes in critical section memleak
    • Does the crash of one application affect the whole system
    • When an application crashes, what happens with its resources like memory chunks, UDS, etc.
  • Update Waitset and Listener section in overview.md and have a use case based comparison
• Add new examples
  • README.md in the example
  • iceoptions
  • icehello
  • iceensemble: Explain how C and C++ API work together (multiple publishers and subscribers)
  • blocking publisher
  • icecubetray: Add access control documentation (comes from Sparse access control documentation. #640)
  • Record asciinema for all examples
• Add example for static RouDi Config with custom mempools and one for the dynamic TOML config, e.b. by just a
• @todo in the code shall not be linked to issues for v1.0
• Add Apex.OS to the framework section

v2.0 Release (Moved to #743)

• Improve utils documentation (in the long run: find more suitable name for utils, e.g. safe building blocks), see also Refine and update documentation #468
• Describe all RouDi command line options?
• Add info about release names (ice cream flavours)
• add overview graphic introducing the main players (RouDi, Runtime/user apps, shared Memory, data packages/topics) in overview.md (see suggestions here and here)
• Add chunk header example
• Add example sending complex data types
• icedelivery: Explain lifetime semantics of chunks/samples and user restrictions: loan needs to be followed with publish or release, MAX_CHUNKS_IN_USE on publisher and subscriber side etc., API is not thread-safe

Consolidate current documentation as far as possible (keep the scope of the issue confined to documentation).
Note: doxygen documentation rework is out of scope here and belongs to #468

This is later to be integrated into the website #136

[elBoberido]

* [ ]  Improve utils documentation (in the long run: find more suitable name for utils, e.g. safe building blocks), see also #468

I suggest iceoryx_hoofs because that's what oryx stands on ;)
My second suggestion is zitzers and my last one roadScorpio.

[FerdinandSpitzschnueffler]

* [ ]  Improve utils documentation (in the long run: find more suitable name for utils, e.g. safe building blocks), see also #468

I suggest iceoryx_hoofs because that's what oryx stands on ;)
My second suggestion is zitzers and my last one roadScorpio.

+1 for iceoryx_hoofs :D

[mossmaurice]

* Introduction: motivation, goals and capabilities of iceoryx

I think it's a good idea to split the description in three major pillars. This makes it easy for newbies to clearly understand what the advantages are. The pillars could be reused for marketing. However, they are still up for discussion in #481 . Could we write the introduction divided into three chapters/pillars so we can link from the front page to them? What do you think?

[MatthiasKillat]

All name suggestions are unprofessional and hard sells in my opinion but I mainly care about content, so whatever. Emphasizing safety as reason why we are implementing these (instead of just using STL in some cases) is important I think.

In other cases, i.e. lockfree constructs the reason is that it is/was not possible to find suitable implementations that work with shared memory and satisfy our safety constraints, so we created our own. Maybe this should be even an extra library.

[elBoberido]

All name suggestions are unprofessional and hard sells in my opinion but I mainly care about content, so whatever. Emphasizing safety as reason why we are implementing these (instead of just using STL in some cases) is important I think.

In other cases, i.e. lockfree constructs the reason is that it is/was not possible to find suitable implementations that work with shared memory and satisfy our safety constraints, so we created our own. Maybe this should be even an extra library.

If we want to go the route, we could have a iceoryx_cxx, iceoryx_posix and iceoryx_concurrent repo. Everything that doesn't fit in those categories lands in the iceoryx_hoofs repo

[orecham]

iceoryx_hoofs or iceoryx_hooves ?

I thought the plural was "hooves" but apparently both are acceptable.

Or, if we are just throwing names out there, icicles ?
I don't have any other arguments other than it sounds cool to me haha.

[elfenpiff]

@elBoberido as a first step I would not split this up in such fine granularity and would create only one separate repo for the utils. If later the need comes up to split it further we can do it but for now we should follow yagni (you aint gonna need it).

+1 for icicles. @ithier one question, the tests for the icicles would then be testicles? ;)

[elBoberido]

in a talk to @mossmaurice I mentioned iceoryx foundation classes in short ifc as possible name for the utils and he quite liked it