[RTEMS Project] #2855: Next generation of RTEMS documentation

[RTEMS trac]

#2855: Next generation of RTEMS documentation
-----------------------------+-------------------
 Reporter:  sebastian.huber  |       Owner:
     Type:  enhancement      |      Status:  new
 Priority:  normal           |   Milestone:  5.0
Component:  Documentation    |     Version:  4.12
 Severity:  normal           |  Resolution:
 Keywords:                   |
-----------------------------+-------------------

Comment (by chrisj):

 Replying to [comment:7 sebastian.huber]:
 > Replying to [comment:6 chrisj]:
 > > Replying to [comment:5 sebastian.huber]:
 > > > I propose to do the following:
 > > >
 > > > 1. Move the documentation back into the RTEMS sources.
 > > >
 > >
 > > Please do not. There is more to the project's documentation than the
 kernel and doing this would result in commit churn.
 > >
 > > How a user uses the RSB or Eclipse is valid user documentation and it
 is not related to the kernel. Having this type of documentation in the
 unrelated kernel source repo would cause 2-way commit churn where user doc
 changes unrelated to the kernel would require buildbot rebuilds of the
 kernel and kernel changes would require documentation rebuilds.
 >
 > Is this a hard buildbot limitation? Why can't you teach buildbot that
 there are separate build systems/components in different directories? We
 don't have that many commits per second. Is this a real problem?

 Currently yes it is. This adds extra complexity to something we have not
 got working and I am concerned about adding extra complexity.

 >
 > I would even consider to move all parts that are required to work with
 RTEMS and that are maintained by the RTEMS project into one repository,
 e.g. the RSB and the RTEMS Tools.

 I suppose you mean creating a '''world''' repo. I can see this being
 possible once the autotools build system goes and we have switched to waf.
 Doing so before that happens would create a level of complexity I would
 not like to consider. As you say we could move the RSB, RTEMS Tools,
 examples into a single repo. I am not sure about networking, ie the legacy
 and libbsd stacks, plus third party packages. They would need some sort of
 ports database.

 I would like to add moving to an '''RTEMS world''' is a different topic
 and bringing the docs repo into a single "world" repo makes more sense. I
 see doing this now as premature.

 >
 > >
 > > For me having the documentation source in the kernel source tree so a
 specific part of the documentation could be automatically updated is a
 questionable small gain at a larger cost. I question any formal user API
 documentation we have being automatically generated this way for a few
 reasons. It becomes difficult to audit changes because you need to de-
 reference the location in the documentation source to the location in the
 kernel source tree and I feel formal user API interfaces should be fixed
 and cannot change without careful consideration rather than being seen as
 kernel source file changes. Second, we have more than one place
 documentation can be located which means more complexity in how we
 maintain the documentation, and finally we would need to find a suitable
 format for use because there is no tool I know of that can do a suitable
 doxygen type extraction to ReST.
 >
 > For the space qualification of RTEMS SMP we have to produce a lot of
 different documents.

 It is difficult to discuss something like qualification documentation when
 we do not know what is needed. I doubt qualification documentation
 requires a suitable Getting Started Guide or how to use Eclipse, these are
 user focused. In relation to qualification artifact generation we should
 endeavor to build into our processes and tools support to generate the
 data the artifacts need, for example the XML reports created by the RSB.

 > I didn't spend much time to this topic so far, but I guess that without
 automatic generation from a common source (XML documents) this will be
 infeasible to deliver.

 Sorry, I do not know what you mean by a common source and XML documents. I
 do not know what the requirements are you are considering here.

 If qualifying requires extra information that is internal then it can be
 automatically generated from source. Again I would like to make a clear
 distinction between user API documentation and anything internal. They are
 not the same thing and do not or even should not be grouped together.

 >
 > >
 > > > 2. Move the BSP README files to the documentation directory into the
 CPU Supplement.
 > >
 > > I wonder if we should have a single document for BSPs and this be a
 chapter. I do not see a need for lots of separated manuals.
 >
 > Yes, we definitely have to reduce the amount of different documents.
 Maybe we should move the BSP stuff into the getting started guide.
 Somewhere there should be a list of supported chips/boards (section)
 grouped by architecture (chapter). The quirks, build options, and so on
 (subsections) should be available for each BSP.

 Should BSPs be a section in the User Manual?

 I am currently adding a Host Tools section to cover `rtems-ld`, `rtems-
 exeinfo`, `rtems-syms`, and `rtems-tld`. Then I will be adding a section
 on Applications to cover that topic.

--
Ticket URL: <http://devel.rtems.org/ticket/2855#comment:8>
RTEMS Project <http://www.rtems.org/>
RTEMS Project