[RTEMS Project] #3738: Refactor the Software Engineering Manual

[RTEMS trac]

#3738: Refactor the Software Engineering Manual
--------------------------+----------------------------
 Reporter:  Gedare Bloom  |       Owner:  Joel Sherrill
     Type:  project       |      Status:  assigned
 Priority:  normal        |   Milestone:  Indefinite
Component:  doc           |     Version:  6
 Severity:  normal        |  Resolution:
 Keywords:  docs          |  Blocked By:
 Blocking:                |
--------------------------+----------------------------
Changes (by Joel Sherrill):

 * keywords:  SoC docs => docs


Old description:

> The newest [https://docs.rtems.org/ RTEMS Manual] is the
> [https://docs.rtems.org/branches/master/eng/index.html Software
> Engineering (SwE)] Manual, which is intended to document the software
> engineering practices of RTEMS development. This project will improve the
> completeness and consistency of the SwE Manual with respect to primary
> sources and our intentions for this manual's use.
>
> One of the main sources of content for the SwE book is our wiki. We would
> like to have the content of the SwE manual cross-checked with the
> respective wiki pages, and have those wiki pages be replaced with a link
> to the SwE book as the authoritative source for the information moving
> forward. This check should ensure the content is correctly reproduced,
> and identify any re-formatting that should be done in the manual to
> improve typesetting etc.
>
> In addition, the flow and organization of the SwE Manual likely could be
> greatly improved. We created the manual by filling in an outline with
> large dumps of text. A balanced and thoughtful approach to the manual's
> organization would likely provide great benefits to its usability and
> maintenance.

New description:

 The newest [https://docs.rtems.org/ RTEMS Manual] is the
 [https://docs.rtems.org/branches/master/eng/index.html Software
 Engineering (SwE)] Manual, which is intended to document the software
 engineering practices of RTEMS development. This project will improve the
 completeness and consistency of the SwE Manual with respect to primary
 sources and our intentions for this manual's use.

 One of the main sources of content for the SwE book is our wiki. We would
 like to have the content of the SwE manual cross-checked with the
 respective wiki pages, and have those wiki pages be replaced with a link
 to the SwE book as the authoritative source for the information moving
 forward. This check should ensure the content is correctly reproduced, and
 identify any re-formatting that should be done in the manual to improve
 typesetting etc.

 * The primary remaining task is to review sections taken from the wiki,
 ensure the conversion looks correct, delete the wiki page, and correct all
 references from the web to the delete page.

 In addition, the flow and organization of the SwE Manual likely could be
 greatly improved. We created the manual by filling in an outline with
 large dumps of text. A balanced and thoughtful approach to the manual's
 organization would likely provide great benefits to its usability and
 maintenance.

--

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