listening to incoming feedback about RIOT, it seems that while we get a
lot of praise for our well-documented API, it seems that people are
missing more high-level concept documentation and more to-the-point
examples on how to do things in RIOT.
Looking at our example code, apart from everything in "tests/" which are
mostly applications used by developers to test certain aspects of the
codes, we only have rather high-level example applications.
I propose to extend these with very simple, condensed example
"applications", where each example just shows how to do a simple task,
like "set up a periodic timer".
Initially I thought about creating a directory structure that
corresponds to either the file system hierarchy or the doxygen group
hierarchy, as in:
"examples/sys/xtimer/xtimer_periodic"
or
"examples/sys/timers/timer_periodic"
But maybe we can even live with one examples directory holding all
examples, as that makes finding them very easy.
Looking at our doxygen, I'd propose to put examples into an "examples"
subgroup for each group that actually has examples.
Do you think more condensed examples would be useful?
listening to incoming feedback about RIOT, it seems that while we get a
lot of praise for our well-documented API, it seems that people are
missing more high-level concept documentation and more to-the-point
examples on how to do things in RIOT.
Agreed.
I propose to extend these with very simple, condensed example
"applications", where each example just shows how to do a simple task,
like "set up a periodic timer".
I think one reason against these applications for now was that all
applications have to be updated once an API change happens (which has been the
case in RIOT rather often). Since we're hoping to reaching a more stable API
soon, this argument may have less weight now.
Initially I thought about creating a directory structure that corresponds to
either the file system hierarchy or the doxygen group hierarchy, as in:
"examples/sys/xtimer/xtimer_periodic"
or
"examples/sys/timers/timer_periodic"
But maybe we can even live with one examples directory holding all examples,
as that makes finding them very easy.
I think I would also prefer a flat hierarchy and keep it simple.
Looking at our doxygen, I'd propose to put examples into an "examples"
subgroup for each group that actually has examples.
+100
(Is it the first time I hear a pro-documentation proposal from your side? ;-))
Do you think more condensed examples would be useful?
What exactly do you mean by "condensed"?
Do you have an opinion on how to structure them?
Not really, I was only wondering if we may limit build tests for these
examples to native, to save load on the CI server.
Initially I thought about creating a directory structure that corresponds to
either the file system hierarchy or the doxygen group hierarchy, as in:
"examples/sys/xtimer/xtimer_periodic"
or
"examples/sys/timers/timer_periodic"
But maybe we can even live with one examples directory holding all examples,
as that makes finding them very easy.
I think I would also prefer a flat hierarchy and keep it simple.
We already have a similar discussion in Issue#3363. I think a structured directory tree is equally easy but more unambigous.
Having the same structure as the source tree is also some kind of basic documentation of dependencies.
Something like e.g. <$RIOTBASE/tests> with ~90 entities and individual pre/postfixing of names makes it not easy to find things or check if things are missing -at least for me-.