[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 sebastian.huber):

 Replying to [comment:1 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.

 I think everyone can get access to this site. You are probably not allowed
 to redistribute the documents without permission.

 Other standards are more difficult to access, e.g. IEC 61508 or DO-178B.

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

 Ok, so the BSP pages from the wiki should move into BSP README files.

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

 It would be really nice to generate the header files with Doxygen comments
 and the sphinx parts from one common file, e.g. in XML. This could be also
 used to contain the specification and test cases.

 >
 > 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:2>
RTEMS Project <http://www.rtems.org/>
RTEMS Project