| SMWCon Fall 2013 | |
|---|---|
| SMW in Technical Documentation | |
| Talk details | |
| Description: | We would like to give a short introduction to established methods in technical writing and typical features of content management systems. Then talk about SMW as tool for writing and accessing documentation. |
| Speaker(s): | Mark Schubert, Jonas Wäckerle |
| Slides: | see here |
| Type: | Talk |
| Audience: | Everyone |
| Event start: | 2013/10/30 01:30:00 PM |
| Event finish: | 2013/10/30 02:00:00 PM |
| Length: | 30 minutes |
| Video: | click here |
| Keywords: | structured authoring, DITA, technical writing |
| Give feedback | |
A wiki can be set up for various purposes one of them is technical writing and documentation. In technical writing there are established methods to guarantee consistent quality of documentation. Structured authoring is widely regarded as best practice.
Semantic features of SMW are very helpful for structured authoring and accessing structured content. We want to give a short introduction to the concepts of structured authoring and typical features of content management systems for technical writers. Then we would like to illustrate how some of these concepts can be realized in SMW and discuss how SMW may improve the experience of SMW users in the context of technical documentation.
We use SMW for intranet documentation platforms. Forms and templates help authors to create structured content and allow easy access to information. Annotating pages and querying properties create functionality that resembles features of content management tools for technical writers.
Contents
Requirements in technical writing[edit]
What is good content?[edit]
Good content is the center point of technical writing. It has to be correct and usable. Without it customers can’t use the full potential of a product, developers have a hard time to use an API that someone else developed, and service technicians might risk their lives installing a new power inverter for solar panels. In this talk we would like to look at the following indicators for content quality.
- Relevant content
- Stuff that matters to the user (solving problems)
- User- and task-oriented content
- Accessible content
- Functional groups of content easy to identify
- Reader must see immediately whether the topic is a procedure (I need to do something), a concept explaining technical background or referencing information, e.g. a list of parameters)
- Must suit different types of readers
- Functional groups of content easy to identify
- Up-to-date content
- Highlight status of content (draft, released, new version)
What factors influence quality of content?[edit]
When it comes to improve or sustain quality of content several factors come to mind. For our talk we would like to group them into two categories:
- Tool-independent factors
- User group analysis
- Minimalistic writing
- Tool-dependent factors
- Allow authors to focus on content quality (reduce unnecessary workload)
- Allow multiple ways to access information
The talk is going to focus on the tool-dependent factor and its underlying methods.
Technical writing tools and methods[edit]
How conventional tools reduce workload of authors[edit]
In technical writing, established methods and tools support the author in producing consistent content of reasonable quality. Structured authoring is considered to be state of the art. It is XML-based and relies on information models that are customized according to the needs of the domain. Popular XML document type definitions used in technical writing are DocBook and DITA. We are going to talk about our experience with DITA in SMW. The following list describes in short how DITA can be used in technical writing and how some conventional tools use it:
- Separate content from layout
- Structured authoring with XML foundation
- Help to organize content by classifying it (DITA)
- Acts as scaffolding to support author who’s is writing the topics and assembling topics into documents (information products)
- Allow to check terminology and phrasing
- Terminology management and authoring tools
- Allow reuse of content
- Reference content multiple times in same document (e.g. conref in DITA)
- Reuse topics for different documents
- Some tools even support building information products by drag-and-drop of content snippets
- Allow to manage variants of content
- E.g. author does not have to maintain several topics that only differ in name of product
- Conditional text allows filtering of content (maps with ditaval in DITA)
- Allow single-source publishing
- Allow to publish content from one source to multiple formats (PDF, webhelp, HTML)
- Support workflow
- Review and discussion of changes
- Release of content
- Allow to manage and publish different versions of content
- E.g. maintain different branches of documentation
- Allow users to comment and contribute to documentation
- Some CMS support review workflow with comments
How conventional tools make content accessible[edit]
Accessibility of content takes the user’s point of view into account. SMW as a wiki is authoring tool and published information product in one. This separates it from most other tools used in technical writing and opens up new possibilities. Technical writing usually produces different output formats. The format of the output heavily impacts how content can be accessed by the user. Accessibility also depends on the type of user.
- Different types of users access content in different ways
- Tony CoverToCover-ReadsItAll
- Lindsey HyperTextBrowse
- John FullTextSearchy
- Ways of access (examples)
- Navigation functions – where am I, which topics are related
- Finding content by keywords (tag), full-text search, or hierarchical table of contents
- Invoke documentation from software user interface in order to directly get help for the window that the user is in
- Accessibility influenced by publishing target
- HTML-based help with FTS, dynamic table of contents, index, hyperlinks, breadcrumb navigation, keyword tags…
- Printed document with table of content, header and footer, cross-references, index…
- PDF with mixture of both
SMW in technical writing[edit]
What’s possible in SMW?[edit]
We are going to show some examples how we tried to model the aforementioned aspects in SMW and discuss our experience. The following list describes how the author was supported:
- Forms and templates allow to separate content and layout
- Still some knowledge of wiki syntax required
- Depending on wiki version support of editors in semantic forms is lacking
- Forms allow classification and harmonized structure of content
- E.g. each procedure requires description of goal and list of prerequisites
- Requires excessive use of free-text properties though
- Queries of properties allow to maintain content in one place and reuse
- Content is up-to-date and maintenance reduced
- E.g. feasible for data sheets of products
- Reuse of longer content can be done by transclusion and templates
- How do you maintain and organize hundreds of content snippets?
Accessibility was improved as follows:
- Properties model relation of information
- Navigation and relations of content is building itself (browse sequence, hierarchy, table of content, breadcrumbs navigation …)
- Also related link lists can be generated
- Content is tagged with keywords
- DITA information types can be browsed by Semantic Drilldown
- E.g show me all procedures that cover a certain subject then list all related reference information
- Properties were used to model workflow and status of document
- In the wiki content is available while people still work on it
- User has to see at first glance if content is draft or released
- Properties influence rendering of page
Open issues?[edit]
There are of course open issues when setting up and using SMW for technical writing. The following list contains some of them:
- Versioning is only feasible for single pages. But in technical writing clusters of content are versioned. How do you branch of an API documentation when a new version of the software is released?
- The mechanism to reuse content is there but there is no easy way to manage snippets of content if a certain number is exceeded. It is not uncommon in technical writing to manage hundreds of self-contained topics that are reused in several information products/manuals.
- Managing variations in content without duplicating huge parts of that content is possible but it makes reuse even more complex.
- Usability can be hard for authors not used to wiki syntax
- Editor support in forms is lacking
- Template picker for standardized text would be nice (e.g warnings according to ANSI)
- Terminology management is possible but requires extensions that were not designed for that (Glossary with forbidden terms)
