[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           |   Keywords:
-----------------------------+------------------
 The RTEMS documentation is inconsistent, confusing and outdated. This is
 the master ticket to define the next generation of RTEMS documentation.
 Individual work packages should be done in separate tickets.

 = Documentation audience

 Who are the consumers of RTEMS documentation?

  Users:: People developing applications with RTEMS.

  Developers:: People doing RTEMS development, e.g. add/maintain BSPs, CPU
 ports, tools, etc.

  Standards:: Some documentation must be provided simply because some
 standard may require it.

  Reviewers:: People that review RTEMS to figure out if documentation,
 source code and executed test programs harmonize and meet certain
 conditions.

 = Existing documentation

 == README files

 #2854

 == Documents

 What to do with the following documents?

 * Getting Started with RTEMS
 * RTEMS Applications C User's Guide
 * RTEMS POSIX API User's Guide
 * RTEMS TCP/IP Networking Supplement
 * RTEMS Shell User's Guide
 * RTEMS Applications Ada User's Guide
 * RTEMS BSP and Device Driver Development Guide
 * RTEMS CPU Architecture Supplement
 * RTEMS Development Environment Guide
 * RTEMS Porting Guide
 * RTEMS POSIX 1003.1 Compliance Guide
 * RTEMS Filesystem Design Guide

 == Wiki

 Purpose?

 == Doxygen

 Purpose?

 Duplicates with user manual?

 = Availability

 Where is the documentation available?

 Provide automatic documentation generation?

 = Standard compliance

 How do deal with standard compliance, e.g. [http://ecss.nl/standards/ecss-
 standards-on-line/active-standards/engineering/ ECSS‐E‐ST‐40C]?

 Some standards require an excessive amount of documents. One option to
 simplify this would be a XML file which defines and documents the RTEMS
 interfaces (data types, functions, defines, macros, etc.) and then use a
 generator to produce header (maybe even with Doxygen comments) files,
 documentation files and also test cases.

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