Online groups, summer 2013
DITA and flow
A book about DITA has much repetition, and the paragraphs are not connected. Is the lack of flow because the book was written using DITA, or is it because the writer is not good?
Some members think that DITA and modular writing usually cause a decrease in the quality of text. Text does not flow between topics. Other members said that for documentation, the flow of text is not important, because people do not usually read all a technical manual from the start to the end. However, DITA lets you link topics.
Modular writing has many benefits, but also, it has costs. If modular writing helps your organization's business objectives, and if the benefits are more than the costs, then DITA is a technology that you can use for modular writing.
DITA is XML, and can be customized. If you want to write documentation that has sequential structure, DITA For Publishers is an option (www.dita4publishers.org).
Authoring tools
A technical communicator uses Microsoft Word to write documentation. He wants to use different software and investigated FrameMaker, Author-it, and MadCap Flare. What other alternatives to Word are available?
Help & Manual is good (www.helpandmanual.com). The software can create large help systems in many different output formats. The technical support is excellent.
Each authoring tool has its strengths and its weaknesses. The software that you buy is dependent on the problem that you want to solve. Make sure that you know what is important and what is only a 'wish-list' feature. Many tools have similar features, but possibly, no tool has all the features that you want.
Members suggested these resources:
- www.indoition.com/online-help-authoring-tool-choosing.htm
- www.indoition.com/online-help-authoring-tools-survey.htm
- http://hat-matrix.com
Terms for touch-screens
For software that is used on a PC and on a mobile device, do you tell users to 'touch' or to 'click' buttons?
Members suggested many terms, but frequently, members did not agree about the terms. Style guides are available, but different companies use different terms. Joe Welinske wrote Developing User Assistance For Mobile Apps. In the book, Joe mentions 'Touch Gesture Reference Guide' (www.lukew.com/ff/entry.asp?1071).
Standard terms help to make sure that readers understand instructions correctly. However, there are conflicting terms for desktop computers and for different mobile devices from different manufacturers. The best option is to make sure that you use terms consistently.
Documentation for APIs
What is API documentation? How does a technical communicator write API documentation? What level of technical knowledge is necessary?
A software developer who became a technical communicator explained that API means Application Programming Interface (https://en.wikipedia.org/wiki/Application_programming_interface).
You must know the programming language in which the API is written. For many programming languages, you must also understand object-oriented design.
In many companies, the software developers write the source API documentation in the source code as comments. Then, they use software such as Javadoc or Doxygen to create the API documentation. A technical communicator reviews the content for completeness, accuracy, and clarity. Possibly, the technical communicator corrects the comments that are in the source code, or possibly, a software developer corrects the comments.
Sometimes, API developers do not think clearly about the users of the API. (The users are software developers.) Typically, the API developers document how the API operates, not what it does and how to use it.
Typically, a technical communicator creates or reviews documentation that shows how to use the API. The documentation includes samples of code.
Members suggested these resources:
- 'Breaking into a speciality market' in Communicator, autumn 2012 is an introduction to documentation for APIs and for software development kits.
- https://apigee.com/about/ has examples of API documentation.
RSS feed