Product SiteDocumentation Site

JBoss Middleware 0.1

JBoss Documentation Guide

The canonical reference for JBoss developers and writers

Edition 1


Jared Morgan

Technical Writer 
Red Hat, Inc Engineering Content Services

Darrin Mison

JDocBook and Publican Interoperability revised content and pom.xml engineering 
Red Hat, Inc Engineering Content Services

Sean Rogers

XML Element Guidelines 
Red Hat, Inc Engineering Content Services

Throughout JBoss Middleware, the amount of user documentation is significant. This guide contains information that will help new and existing JBoss projects author XML documentation to a common technical and content quality standard. JBoss projects will benefit from the information regarding XML structure, and specific grammar guidelines. By following the recommendations in this guide, your JBoss project will have the style and XML usage information necessary to create professional open source software user documentation; be able to leverage JBoss' wider content, editorial, and translation infrastructure; and be able to easily contribute downstream content to supported products, and accept contributions, including translations, from products downstream.

1. License
2. Document Conventions
2.1. Typographic Conventions
2.2. Pull-quote Conventions
2.3. Notes and Warnings
3. We Need Feedback!
4. Acknowledgements
1. Introduction
2. eXtensible Markup Language
2.1. Advantages
2.2. Role in JBoss Middleware
2.3. XML References
3. Authoring Tools
3.1. Syntext Serna
3.2. oXygen XML Editor
3.3. XML Copy Editor
4. Publishing Tools
4.1. Maven jDocBook
4.2. Publican
5. JDocBook and Publican Interoperability
5.1. Introduction
5.2. Prerequisites
5.2.1. Install Maven
5.2.2. Install Publican
5.3. Create Book Repository
5.4. Build with Publican
5.5. Build with jDocBook
5.5.1. xi:include Fallbacks
5.5.2. Insert .ent Parameter Entities
5.5.3. Configure pom.xml
5.5.4. Publish with jDocBook
5.5.5. Begin Authoring
6. Structure Guidelines
6.1. Disallowed Elements and Attributes
6.1.1. Disallowed elements
6.1.2. Disallowed attributes
6.2. Entities
6.3. Chapters and Sections
6.4. Lists
6.5. Procedures
6.6. Tables
6.7. Emphasis (Bold, Italic, Underline)
6.8. Graphics and Screenshots
6.9. Admonitions (Warning, Important, Note)
6.10. Special Characters (Symbols)
6.11. Menus, Buttons, and Labels
6.12. Applications and Utilities
6.13. Code Examples
6.14. Links and References
7. Language Guidelines
7.1. Dictionary
7.2. Active Voice
7.3. Tense
7.4. Gender References
7.5. Sentence Structure
7.6. Conversational Language
A. pom.xml Multi-Profile
B. Sample Project
B.1. Default Folder Structure
B.2. Book Components
B.3. Customizing Book Structure
C. Revision History