Categories

Users Online

+ 2 Guests + 3 Bots

Basic Software Documentation Terms You Should Know

User Guide vs. System Admin Guide© Ugur Akinci

(Thanks to Deepti K. for her kind contribution to this list.)

It helps to know what the following are if you’re documenting any software products. It cuts down on your preparation time and saves you from getting those “funny stares” from the developers/engineers when it becomes apparent that you don’t know what you’re talking about.

Rule of thumb: always do your homework first and get the lingo down before approaching an engineer for more information.

So, make sure you’re familiar with these concepts (it helps at job interviews too):

  • A “build”
  • A “release”
  • Release notes
  • A “bug”
  • A “show-stopper bug” (or “a Blocker issue”)
  • “Bug tracker” or just plain “Tracker”
  • SourceSafe
  • Version control
  • Configuration
  • Configuration Management (also check out: Agile, a CM software)
  • Specs (or Requirements)
  • Functional specs (or Functional Requirements)
  • MRD (Marketing Requirements Document)
  • Scope document
  • Design document
  • Database (DB)
  • Relational database
  • Flatfile database
  • System architecture
  • N-tier system architecture
  • Client/Server
  • Client-side vs. Server-side (as in “Javascript is a client-side script but PHP is not”)
  • A “script” and its difference from a  “[programming] language”
  • Difference between Javascript and Java
  • Test Cases
  • Use Cases
  • Hot fix or a Patch
  • and basic terms from the Agile environment

Let me know if you can remember any other SW terms to add to this list or you need help with any of these terms.

Share

Goal-Focused and Structured Technical Writing

© Ugur Akinci

PREMISE

  • Most of the technical documentation that exists in the world today is feature-focused.
  • It is also unstructured: there is no well-defined hierarchy between the components of the document. For example, there is no enforcement of a hierarchical rule like “every task description shall be followed by a reference section.”

PROBLEM

Most of the time the end-user has a problem to solve, not a desire to read every feature of an option. Most of the current documents do not address that end-user need since they are not written with a goal-focused framework.

FEATURE-FOCUSED TECHNICAL DOCUMENT STRUCTURE

Feature-Focused Technical Document Structure

SOLUTION

  1. Start from GOALS, that is, what the users are trying to achieve or keeping them awake at night.
  2. Determine the ACTIVITY that will make reaching that goal possible.
  3. Provide the essential INFORMATION that will make that activity possible.

EXAMPLE

  1. GOAL: To allow contractors into a site only during certain hours of the day.
  2. ACTIVITY: Create a CONTRACTOR user type with limited access code.
  3. INFORMATION: Steps to follow to create a “Contractor” user type with limited access code.

GOAL-FOCUSED TECHNICAL DOCUMENT STRUCTURE

Goal-Focused Technical Document Structure

3-TOPIC FRAMEWORK

This goal-oriented structure requires documents be written according to a 3-topic document framework currently used by some Fortune 100 corporations like Rockwell International.

  • DITA: These are the standard structured-authoring topic categories used by DITA (Darwin Information Typing Architecture) scheme. Thus, re-writing our documents by “bursting” the current feature-laden catch-all topics into smaller and leaner more-granular topics would provide a smooth transition to XML-based structured authoring as well.
  1. First topic: CONCEPT. Answers the “What is?” question. Derives from the customer GOAL or PAIN POINT.
  2. Second topic: TASK. Answers the “How do I do it?” question. Derives from the ACTIVITIES INFO needed to achieve that goal.
  3. Third topic: REFERENCE. Answers questions like “What are the specs?” or “What is the list of all the commands available?” Derives from the FEATURES DATA to support the activities in question.

BENEFITS

  1. CONSISTENCY. The topic rules built into a structured document are enforced by the structured authoring software (like Structured FrameMaker). This builds user confidence in the documents and creates a more positive user experience.
  2. MINIMALISM. Topics are kept to a minimum. Each topic addresses only one finely-tuned issue. User fatigue and cognitive overload are kept to a minimum. Comprehension and retention are maximized.
  3. REUSABILITY. Since topics are granular and modular, they can be reused in combination with other topics. For example, a topic that describes how to configure access codes can be used with creating a contractor user type. This lowers cost of authoring.
  4. LOWER COST OF LOCALIZATION. This type of documentation has proven to minimize the costs of localization.
  5. SINGLE SOURCING. Once created, this type of XML-based documents can be delivered on a number of different platforms by using the same source files, including HTML5 responsive-layout deliverables for mobile platforms, Kindle and ePub formats, MS HTML Help, Web Help, and like.
  6. ECONOMY OF UPDATES. To update such documents it is not necessary to update each deliverable individually. Once the XML-based source files are updated, they can be republished and pushed on to different delivery platforms. This lowers cost of production and distribution.

WHAT IS NEEDED?

  1. Goal-oriented structured documentation require management by-in. Without management support, the shift from unstructured to structured authoring cannot be accomplished.
  2. The writers need to have access to “customer pain-point” data. Without such data the writers would not know what the important documentation GOALS are.
  3. The writers and the management need to have consensus on the “framework,” that is, the kind of TOPICS that will be included in the documents.
  4. Additional tech writing hours may be needed to sift through both the customer goals and break down topics to individual CONCEPTS and then rebuild them again into a structured document. The initial phase might be very labor-intensive indeed. But once it is done, future updates should be easy and less labor-intensive.
Share

Avoid “Double Possibility” in Your Statements

7 Different Types of Fundraiser Letters© Ugur Akinci

George Bernard Shaw once wrote a very long letter to a friend and ended it with the following post script: “Sorry, I didn’t have the time today to write you a short letter.”

Clean technical writing is easy if you have the time to go over what you’ve written. My experience is, almost any sentence you’ve written can be made shorter and shorter is usually (even though not always) better.

One guaranteed way to shorten your sentences is the willpower to resist using double possibilities.

Here is an example:

ORIGINAL: “Warning: If you click the YES button you may end up losing data.”

Here “if” represents the first POSSIBILITY since it depends on a condition. “May end up” is the second POSSIBILITY, which does not add anything new to the sentence.

The sentence was already conditional before the “may end up.” It remains equally possible after that.

Thus we can safely eliminate the second possibility.

BETTER: “Warning: If you click the YES button you may lose data.”

Share