From Fedora Project Wiki
No edit summary |
No edit summary |
||
| (4 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
* [[Docs Content Specs]] | |||
'''Introduction''' | '''Introduction''' | ||
- Be bold! | - Be bold! | ||
| Line 25: | Line 27: | ||
- Entities: With great power comes great responsibility | - Entities: With great power comes great responsibility | ||
'''Tasks, Procedures, and Processes''' | '''Separation of Concerns''' | ||
Note: Each of these may be an overview here, and a dedicated chapter each | |||
- Separation of Concern pattern explained | |||
- Separation of Content and Presentation | |||
- Usability | |||
- Document metadata | |||
- Publican brands | |||
- Separation of Domain Knowledge and Information Architecture | |||
- Domain Knowledge | |||
- Documentation Information Architecture | |||
- Separation of End-user Problem space and Technology Solution space | |||
- End-user problems | |||
- Technology-specific solutions | |||
- Separation of Audiences | |||
- Organizational roles | |||
- Separation of Information types | |||
- Mental processing modes | |||
- Separation of document life-cycle phases | |||
- Planning | |||
- Development | |||
- Evaluation | |||
- Editorial | |||
- QA | |||
- Bug reports | |||
'''Information types: Concepts, Tasks, and References''' | |||
- Information types explained | |||
'''Documenting Tasks, Procedures, and Processes''' | |||
- Tasks, Procedures, and Processes defined | - Tasks, Procedures, and Processes defined | ||
- Documenting Procedures | - Documenting Procedures | ||
- The Four Parts of a Procedure | |||
- Procedure-writing Guidelines | |||
- Example Procedure | |||
- Example Procedure Docbook source | |||
- Documenting Processes | |||
'''XML tools''' | '''XML tools''' | ||
| Line 45: | Line 75: | ||
- Validating XML Code | - Validating XML Code | ||
- Building a document | - Building a document | ||
- Publishing a Document to the Web | - Publishing a Document to the Web [https://fedoraproject.org/wiki/Publishing_a_document_with_Publican] | ||
- Draft documentation [https://fedoraproject.org/wiki/Publishing_draft_documentation_using_Publican] | |||
Latest revision as of 01:29, 23 June 2011
Introduction
- Be bold! - Don't let the tools scare you - There's a team to back you up
Documentation Workflow
- Write first, format later - Formatting in DocBook - Pushing strings to translation - Pulling strings from translation - Building documents - Publishing documents to the web - Building packages from documents
Brief Introduction to DocBook
- Why DocBook? - DocBook as an XML markup language - Human-readable tags - Text-based format for easy revision control - Separation between content and style - Output in a variety of formats - Parts of a DocBook file - Common DocBook tags - Dividing a document into multiple files with XIncludes - Entities: With great power comes great responsibility
Separation of Concerns Note: Each of these may be an overview here, and a dedicated chapter each
- Separation of Concern pattern explained
- Separation of Content and Presentation
- Usability
- Document metadata
- Publican brands
- Separation of Domain Knowledge and Information Architecture
- Domain Knowledge
- Documentation Information Architecture
- Separation of End-user Problem space and Technology Solution space
- End-user problems
- Technology-specific solutions
- Separation of Audiences
- Organizational roles
- Separation of Information types
- Mental processing modes
- Separation of document life-cycle phases
- Planning
- Development
- Evaluation
- Editorial
- QA
- Bug reports
Information types: Concepts, Tasks, and References
- Information types explained
Documenting Tasks, Procedures, and Processes
- Tasks, Procedures, and Processes defined - Documenting Procedures - The Four Parts of a Procedure - Procedure-writing Guidelines - Example Procedure - Example Procedure Docbook source - Documenting Processes
XML tools
- XML concepts - xmllint - xsltproc - xmltidy
Publican
- Publican Workflow - Creating a Blank Document - Validating XML Code - Building a document - Publishing a Document to the Web [1] - Draft documentation [2]