From Fedora Project Wiki

(Created page with "'''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 DocBo...")
 
 
(5 intermediate revisions by the same user not shown)
Line 1: Line 1:
* [[Docs Content Specs]]
'''Introduction'''
'''Introduction'''
  - Be bold!
  - Be bold!
Line 24: Line 26:
  - Dividing a document into multiple files with XIncludes
  - Dividing a document into multiple files with XIncludes
  - Entities: With great power comes great responsibility
  - 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 tools'''
Line 36: 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]