Product Definition
Content Management assimilates Help Authoring
[V 1.0]
During the process of tool evaluation it becomes mostly necessary to rearrange the requirements. Sometimes there is even a need to rearrange the existing tool definitions. This Article describes a case based on the domain "Help Authoring Tools" (HAT) which is effectively assimilated by the domain "Content Management Systems" (CMS). Important to Realize
- Even non-complex products result in complex/multiple documentation
- The help system is a part of the whole product documentation.
o Help, Brochures, Readme's, Website... o The product documentation involves the business website.
- HA is a complex process, which needs efficient managing support by the tool.
o
This remains true, even if the complete documentation is written by one person.
Help Authoring Evolution
- Writing electronic help systems for applications
o e.g.: Windows: RTF source compiled to .hlp
- Help Authoring Tools (HAT) simplify the process of creating the RTF file
o Help specific domain knowledge still used during authoring
- Output as electronic and printed help.
- Single Source, Multiple Format Output (.hlp, .chm, .pdf, ...).
- Single Source, Multiple Format Output, Multiple Destination (desk, webpage, print)
- Complexity that must be mastered increases.
o Help Authoring becomes essentially a task of Content Management.
Redefining Tool Category "HAT"
An efficient HAT is basically
- A Managed Authoring System with Several Help Formats output
- A Single Source Authoring Tool with Multiple Output Formats which includes Several Help Formats and CMS functionality
- A Single Source based CMS with Multiple Output Formats, including Several Help Formats.
HAT Category Ejected by Redefinition
- HAT's which have evolved from pure HAT to single source / multiple output tools (PDF, HTML, HTML HELP, etc.), but remain help centric.
- HAT's which do not provide CMS functionality
Specific HAT's Ejected by Redefinition
Basic Requirements
- General Application Requirements
- The Resulting Concrete Functional Requirements
o Creation: editor, layout, styles, paragraph, rules, ... o Change: of created elements, template based output, CSS based layout, on the fly modification with visible results, ... o Reuse: of created elements (paragraphs, styles, ettings, ...), including reuse for corporate website o Automation: content generators, e.g. subsection lists like "See Also", indexing, keywording, ... o Management: creation/change/reuse/automation assistance, versioning, workflow, ... o ...
Final Concrete Requirements
- Combine concrete requirements [functional, implementational].
- Prioritize requirements based on corporate needs.
Evaluation
- Select tools to evaluate
o Single Source Authoring Tools with Multiple Output Format, including Help o Single Source XML based Authoring Tools with Multiple Output Format, including Help o CMS with Multiple Output Format, including Help o ...
The Complex Tools Category
- Have a higher setup time and learning curve.
- Need consultancy / training
o Evaluate if this is really necessary. o Evaluate why the tool does not fulfill "The Implementation Requirements".
Simple Evaluation Sequence
- Setup Project
- Add some Topics and create the inital Table of Contents (TOC)
- Insert an automaticly generated subsection list into a topic (e.g.: "In This Section")
o Use this subsection list in another topic in another section
- Build: create the help file in different formats in one step
o Repeat the same build from the command line.
- Change the generated Layout (text styles, paragraph styles, ...)
o How and when did the output reflect the changes?
- Rearrange the TOC whilst keeping a the initial one (multiple TOC)
- ...
Simple Reuse Scenario
- An HTML Help System is written for a software product
o It contains a paragraph "System Requirements"
- The identical paragraph is used in the "readme.txt" and in a page of the product website
o Create the help file, the readme.txt and the webpage in one step