Difference between revisions of "Blueprint-os-modularize-admin-docs"
(Created page with " * '''Launchpad Entry''': * '''Created''': Nicholas Chase * '''Contributors''': == Summary == Develop a system whereby the overall Administration Guide is created through ...") |
m (→Summary) |
||
| Line 5: | Line 5: | ||
== Summary == | == Summary == | ||
| − | Develop a system whereby the overall Administration Guide is created through the inclusion of content that makes up individual | + | Develop a system whereby the overall Administration Guide is created through the inclusion of content that makes up individual guides. |
This will make it possible to create a comprehensive Administration Guide while still making it possible to create smaller guides for those who are overwhemed by the big picture or are just looking for information on a single topic. | This will make it possible to create a comprehensive Administration Guide while still making it possible to create smaller guides for those who are overwhemed by the big picture or are just looking for information on a single topic. | ||
Latest revision as of 21:26, 11 August 2013
- Launchpad Entry:
- Created: Nicholas Chase
- Contributors:
Contents
Summary
Develop a system whereby the overall Administration Guide is created through the inclusion of content that makes up individual guides.
This will make it possible to create a comprehensive Administration Guide while still making it possible to create smaller guides for those who are overwhemed by the big picture or are just looking for information on a single topic.
Rationale
Currently, there is concern that the Compute Admin Guide is "comprehensive to the point of being useless." On the other hand, there are so many manuals, users are sometimes overwhelmed just trying to figure out where to go for information. The purpose of this project is to create a framework where we can have a comprehensive book, but still enable the creation of smaller books out of the same information.
Design
The system:
- Creates the overall Administration Guide
- Creates any smaller admin guides that aren't already covered by their own guides
- Relies on a single Docbook file that includes all of the content
- Requires additional maven goals within generate-sources to create any additional necessary guides
Issues
- Some books (such as Compute) need to be rewritten so if they're included now, the Docbook will need reworking afterwards.
- Some books are written with prefaces and appendices, so they can't have their chapters included raw. Instead we will need to pull the contents of the chapter, either through XSLT or XPointer
- We need to determine which books need to be generated from this process, and which stand on their own.
