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

 In regards to the ESA link, the license needs some clarification. We have
 ECSS members and non-members and it is not clear to me what the actual
 intent of the license is. Also accessing the docs needs a login and
 password and I am not sure what is involved in getting them, however RTEMS
 is open source so should we reference "behind a wall" docs? I would prefer
 we do not if that can be done.

 The wiki needs to be general and contain information not version or
 release specific information. We cannot snapshot the wiki and provide it
 as part of a release. Take for example the removal of the SIS BSP in 4.12,
 that BSP still exists in 4.11, 4.10 etc, so if the BSP documentation,
 generated, post processed or otherwise is in the wiki do you delete all
 references to the SIS in the wiki so the content is valid for 4.12 or do
 we leave the information in the wiki for those 4.11, 4.10, etc users who
 still have that BSP. A wiki great for developer documentation and
 workflows, or fluid things like a step through of booting a PC with PXE,
 iPXE, etc to RTEMS.

 Doxygen. I do not agree with formal API documentation being generated from
 the source for users. A user manual for a formal API needs to be user
 focused with all error, conditions of use, and real examples. An API
 interface is a formal contract between the developers of RTEMS and users
 that these interfaces are stable and do not change. There will be
 duplication for API functions however I do not see this as a problem
 because the churn on these interfaces should be almost nothing. For
 internal or developer documentation doxygen is great, there are others
 such as Linux Kernel Cross-Reference (LXR). I use http://fxr.watson.org/
 from time to time.

 Finally I would like say how excited I am by the chat, tickets and focus
 on the documentation. If getting the docs with what ever content into
 Sphinx has helped start this process then I am happy.

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