[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: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.

 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 source
 tree and I feel formal user API interface should be fixed and cannot
 change without careful consideration rather then 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.

 > 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 see not need for lots of separated manuals.

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