From Fedora Project Wiki
No edit summary |
No edit summary |
||
| (2 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
* [[Docs Content Specs]] | |||
'''Introduction''' | '''Introduction''' | ||
- Be bold! | - Be bold! | ||
| Line 26: | Line 28: | ||
'''Separation of Concerns''' | '''Separation of Concerns''' | ||
Note: Each of these may be an overview here, and a dedicated chapter each | |||
- Separation of Concern pattern explained | - Separation of Concern pattern explained | ||
- Separation of Content and Presentation | - Separation of Content and Presentation | ||
| Line 41: | Line 44: | ||
- Separation of Information types | - Separation of Information types | ||
- Mental processing modes | - Mental processing modes | ||
- Separation of document life-cycle phases | |||
- Planning | |||
- Development | |||
- Evaluation | |||
- Editorial | |||
- QA | |||
- Bug reports | |||
'''Concepts, Tasks, and References''' | '''Information types: Concepts, Tasks, and References''' | ||
- Information types explained | - Information types explained | ||
'''Tasks, Procedures, and Processes''' | '''Documenting Tasks, Procedures, and Processes''' | ||
- Tasks, Procedures, and Processes defined | - Tasks, Procedures, and Processes defined | ||
- Documenting Procedures | - Documenting Procedures | ||
| Line 65: | 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]