Question

"Evaluation of Documentation Tools" Please respond to the following:

• You have been assigned to analyze the accounting information for a Fortune 500 corporation. From the e-Activity, evaluate which tools you would use to analyze its business processes, indicating your rationale.
• On the other hand, resources, such as accountants, business analysts, and I/T specialists who rely on documentation tools, will need proper training on these tools. You have been given the responsibility of familiarizing your team with these tools. Evaluate which techniques, in terms of their appropriateness, you would use to get your team ready for its first assignment—the evaluation of a firm’s internal control structure.

Answer 1

The process of evaluation of documentation tools to analyze the corporation's business process are as follows :

2-Examination Refer to data section (table below) in order to quantify. After referring to data, identify the type of examination. Circle the type of examination within the appropriate grid in Section5 Note: Choose 1995 or 1997 rules, but not both Calculation Choose either 1995 or 1997 rules to calculate result 1995 Body areas: ロone body area or □ 2-7 areas or systems (Minima detail for areas □ 2-7 areas or systems (Expanded documentation of ロ8 or more systems on y Head, inc Chest, including breast and axillac and or systems examined; check list type documentation without any expansion of documentation of findings) the areas and/or systems examined; requires more than checklists, needs to have normal/abnormal findings expanded upon) system Back, including spine Genitalia, groin, buttocks Each extremity 1997 1-5 bullets (I or 6 bullets (1 or more body areas or system) 12 bullets in 2 or more body areas/systems or 2 2 bullets in 9 or more Organ systems: more body areas or system) bullets in 6 or more body areas/ systems (except cye and psych exams, which are 9 bullets) body areas or systems; or complete single organ system Constitutional (c g, vitals, gen app) Ears, nose, mouth, throat Respiratory GI GU Skin Neuro Psych Hemlymph/imm Eyes Final Results Problem Focused Ex Problem Focused Detailed Comprehensive

There’s a question that often pops up in communities I’m a part of: “What tool should I use to write my technical documentation?”. It’s a valid question, but so is “What car should I buy?”. There is no single right answer: any number of cars could be right for you, depending on your needs. Although the same is true for documentation tools, I’m going to give you part of an answer anyway.

While I’m not an authority, I’ve been a technical writer for several years and know the landscape fairly well. I have either worked with or tried most mainstream tools, both commercial and open-source, and have a good sense of their strengths and weaknesses. I’ll share what I know, in the hopes that it helps you get started. Let me know if it does!

Before we dive in, I should point out what I won’t cover:

• Word processors (e.g. Microsoft Word): Yes, you can write technical documentation in Word. Many people do. However, Word wasn’t designed with technical writing in mind, and it shows as soon as you try to follow any kind of best practices for technical documentation. I wouldn’t recommend using a standard word processor for anything beyond a short, one-off publication.
• Documentation generators (e.g. Doxygen, Javadoc): These are specifically for documenting software source code. What they do is go through your code and compile a document based on code patterns and comments. This helps other programmers quickly make sense of your code. Learn more here.

Tool categories

Roughly, the tools available today fall into 4 categories: help authoring tools, wikis, static site generators, and SaaS solutions. Read on for an explanation of each one.

Help authoring tools

E.g.: MadCap Flare, Adobe RoboHelp

These are aimed at professional (technical) writers. Help authoring tools (HAT) enable writers to manage virtually every aspect of producing the documentation themselves, from writing, to design, to publishing, to translation. This usually requires little knowledge of web design or coding. A HAT is therefore especially useful for a technical writer working by themselves or in a non-technical team.

HATs are powerful, but take time to master. Don’t expect to be up and running quickly. Also, they don’t always lend themselves well to collaboration. Content tends to be isolated in the tool, which means getting contributions from non-writers requires either giving them access (and training), or setting up some sort of export/import process. This can make reviews and other cooperative tasks cumbersome.

More about help authoring tools:

• Choosing a help authoring tool
• List of help authoring tools (Wikipedia)

Wiki platforms

E.g.: Confluence, MindTouch, MediaWiki

Wiki platforms (the most famous example being Wikipedia) are aimed at collaboration. They tend to focus on ease of use, removing as many barriers to contribution as possible. This makes them a quick way to get from nothing to something: it’s a matter of a few clicks to create, review and publish a page of content. A wiki is great for teams without a dedicated writer who need an easy way to create content and aren’t that worried about having a solid information architecture.

Where wikis offer solutions, they unfortunately also create problems. They may be simple to use, but that’s usually because their functionality is quite limited. And while they may enable everyone to contribute, they rarely allow a technical writer to effectively curate and structure content. Wikis also commonly suffer from bystander effect: when everyone can create and update content, almost no one does. In my experience, wikis are more useful for internal knowledge sharing than for external publishing.

More about wikis:

• Wiki Choice Wizard
• List of wiki software (Wikipedia)

Static site generators

E.g.: Jekyll, Sphinx, Asciidoctor

This is the ‘techy’ category. Static site generators (SSG) are often associated with the Docs as Code movement. In a typical scenario, technical writers produce content in a lightweight markup language like Markdown or reStructuredText, and store it in a source code repository like Git or Subversion. The SSG turns this content into a set of static HTML files, which are then uploaded to a website. (You’re looking at an example right now: this website was generated by Hugo!)

This approach offers much flexibility: you can choose your own text editor, your own markup language (provided your SSG supports it), your own source control environment, your own hosting solution, etc. It’s also especially suited to software documentation: the content format is familiar to programmers, which encourages contributions, and most SSGs offer software-specific features, such as support for code snippets and UML diagrams. Last but not least, many popular SSGs are open-source, i.e. free.

SSGs aren’t for everyone. A documentation toolchain involving a SSG requires a fairly technical person to maintain it. You should be comfortable with command line interfaces, HTML, CSS, and checking code out of and into repositories before you consider using a SSG. Prominent tech writer and blogger Tom Johnson also points out a few other limits to the ‘Docs as Code’ approach.

More about static site generators:

• Top Open-Source Static Site Generators

SaaS/hosted solutions

E.g.: Paligo, Corilla, ReadTheDocs

SaaS (Software as a Service) is a licensing model under which you pay a periodic subscription fee in return for access to a piece of software, as well as support and service from the publisher. The software often runs in your browser, which means you don’t need to install, host or serve anything yourself. It’s like renting a house rather than buying it.

When you apply the SaaS model to documentation software, what you get is a fully hosted, scaleable solution for authoring, reviewing, and publishing. This is obviously an attractive option for organizations that don’t have the resources to set up and maintain an entire toolchain themselves. They simply pay the monthly fee, and the publisher takes care of everything for them. This type of software is also sometimes called PaaS, or Platform as a Service.

The other side of the SaaS/PaaS coin is that it may be difficult (if not impossible) to migrate your content to another solution if you ever need to. Also, most of the newer SaaS tools seem aimed towards software developers and other non-writers. They appear to trade sophistication for ease of use, lacking many of the essential features a professional writer has come to expect. Still, a SaaS tool could be just the ticket for a modestly-sized development team with minimal documentation needs.

More SaaS tools:

• Readme.io
• Zendesk Guide
• Nuclino

So, how do I choose?

The above should give you an idea of where to start. Unfortunately, that’s about as far as I can take you. The rest comes down to the unique characteristics of your documentation project. I recommend you write down all your must-haves and nice-to-haves in a list, and use that list to evaluate each tool.

Of course, some factors are more decisive than others. Here are a few things I have found can really make or break the suitability of a tool.

Target audience

Who is going to read your documentation? And at least as importantly: who’s going to write it? The easier you make things for both sides, the better the result. You should know when, where and how your content is going to be consumed. If you’re documenting a complicated piece of software, context-sensitive help might be a must-have. That’s going to eliminate some options right away. If your reviewers are always overworked, ensure they don’t need to jump through hoops to comment on your drafts.

Print output

Depending on the industry you’re in, print output can be anything from the norm to ‘not done’. If you do need to publish in print, there are all kinds of special considerations that require specialized tools. What’s more, you might need to publish the same documentation in both print and digital form. Since you probably don’t want to write everything twice, you’ll need a tool that can create multiple outputs from the same source. Not all tools can do this (although most help authoring tools can).

Translation/localization

Translation can ruin everything. Dramatic, I know, but it’s true – take it from a former professional translator. If you already know your documentation needs to be translated at some point, investigate your options in the earliest stage possible. Don’t put it on the list of bridges to cross when you get there, because you’ll regret it. Make sure you choose a tool that offers either:

• effective built-in translation features, such as easy export/import, in-context translation and workflow management, or;
• a solid integration with a good CAT Tool, like SDL Trados or MemoQ.

DITA

Darwin Information Typing Architecture(DITA) is a type of XML for technical writing. If you need to write in DITA (and the choice may not be up to you), there are only a few tools you can use. Some popular ones are Oxygen and XMetal for writing, and DITAToofor source control.