From Fedora Project Wiki
No edit summary |
No edit summary |
||
| Line 44: | Line 44: | ||
- Mental processing modes | - Mental processing modes | ||
'''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 67: | Line 67: | ||
- 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] | |||
Revision as of 00:56, 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
- 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
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]