Why would you write subjects as an alternative of paperwork? It’s simpler to put in writing subjects than to put in writing a doc, sort of like strolling a protracted distance is less complicated in case you take it one step at a time. Subjects are additionally simpler for reviewers to evaluate and for testers to check. Of all these easy-to-write subjects, duties are the simplest of all to put in writing.
Matter-based authoring means you write subjects, not paperwork. The subjects are then assembled into print documents-manuals, guides-or on-line assist. Matter-based authors describe subjects by kind: idea, process, and reference. You’ll be able to create different much less widespread varieties however I need to give attention to these.
Process subjects are simple to establish since they include only a process and nothing else. Process subjects are simple to put in writing for a similar motive. It’s simpler to put in writing duties than another kind of technical writing, particularly in case you aren’t slowed down questioning what else it is best to embrace. The reply is nothing. That is an absolute. You write the subject title, then the steps, and embrace nothing else besides perhaps a ‘Extra info… ‘ hyperlink. Okay, sometimes you may embrace a Observe or a Warning of some kind, however nothing else.
Idea and reference matter varieties are harder to quantify however simply as simple to put in writing. Usually, idea subjects are descriptive of a common space of data, corresponding to an introduction or principle of operation.
Reference subjects, alternatively, include info that the reader may must entry to finish a process. Reference info might be a desk of spark plugs by automotive kind, a listing of widespread symbols used on medical gadgets, or a pricing index. Data the consumer may have however that shouldn’t be of their face except they need it particularly.
Guidelines and Tips of Matter-based Authoring
The primary rule of topic-based authoring is to put in writing all of the duties first. This was tough for me-at first. I used to put in writing from the highest down and from the entrance to the again. It simply felt logical. Certain, I encountered pitfalls with shoehorning missed or added info into already written chapters, however that was the best way issues have been. Proper?
In opposition to my higher judgment, and my twenty years of expertise, I took the problem and started writing duties. After all, which means that every process is in its personal file, which felt very unusual. Nevertheless, the end result was superb. I might nearly instantly see the good thing about writing simply the duties and writing every process as a single matter:
- I painlessly gained data of the product by specializing in what every aspect of the product or software did.
- I used to be in a position to prepare and rearrange the subjects as new data got here to me.
- I not needed to shoehorn any info. When the challenge staff got here up with a brand new characteristic, I might write the duties and shuffle them in the place they belonged.
- I instantly saved on translation prices. Writing solely the duties, I noticed lots of the phrases have been the identical from process to process and began leveraging these phrases. In any case, the extra actual matches, the higher.
- I might cut back redundancy in my writing. As I used to be writing the subjects, something that wasn’t a process went right into a ‘later’ folder. Once I pulled out that folder, I might clearly see which items have been reference items so I began placing these collectively. I might simply weed out any redundancy that happens when duties have the identical extra info.
After writing all of the duties, or the entire duties you understand about on the time, what do you do with all of the items of data which can be within the ‘later’ folder? These are items of data like why you choose this feature over that possibility or what every possibility means.
Once I lastly wrote the reference subjects, most of them ended up as tables or bulleted lists. When reviewing duties, you’ll be able to add cross-references to those subjects, as wanted. Or, if you’re authoring in DITA, you’ll be able to create a reltable in your ditamap. That is very cool and, if given the chance, it is best to attempt it.
Not often do you want idea info for on-line assist. Idea subjects often solely come into play in print paperwork. If you’re single-source authoring, you’ll be able to rearrange and reuse these identical subjects you created for the web assist on your print paperwork however you often want so as to add these introductory items I discussed earlier. See what I did right here? I moved the dialogue from topic-based authoring to single-source authoring. Truly, they go collectively.
For instance, in a Customers’ Information, you would write an idea matter for the start of every chapter. When needed, you would embrace an idea matter throughout the chapter for a piece of like info. As a result of these are all particular person subjects, you’ll be able to prepare them a technique for one kind of output-a handbook or guide-then rearrange them with extra or fewer subjects for an additional kind of output-online assist or a Fast Reference doc.
I acquired these outcomes after I first used topic-based authoring:
- My phrase depend went down.
- My actual matches for translation went up.
- Our on-line assist usability scores went means, means up.
Some Suggestions and Methods
Some habits we type when writing can hang-out us and breaking these habits is tough. Nevertheless, listed below are some issues I realized:
- If writing from necessities paperwork, or getting your info from builders, be sure you usually are not offering extra info than the end-user wants.
Some builders need all of their thought processes included and the consumer actually, actually doesn’t care about what it took to get this management to work on this surroundings. Additionally keep away from advertising messages. They already purchased the system or software and actually do not need to be beat over the top with how nice it’s.
- Finish-users additionally don’t need to examine a end result that they’ll see occurring.
For instance, don’t inform them that once they choose Filter, the Filter window opens. If choosing a management launches a sure window, like a Filter window, they’ll see it. For those who actually should embrace affirmation of some kind, begin the subsequent process with, “On the Filter window,… ” That ought to inform all of them they have to be certain they’re in the fitting place.
- For those who write a subject a few operate that’s carried out in one other window, you’ll be able to often do a reduce and paste of some steps for that window. For instance, in case your matter is Filtering Controls, step one might be one thing like, “On the menu bar, choose Filter.”
The filter window itself has a assist button, in fact, so copy all of the steps from the “Filtering” matter besides step one. Copy and paste Steps 2 by way of N into your Filter dialog field matter and you’ve got saved some work. Moreover, you now have steps which can be an actual match for translation functions.
In anticipation of your query, sure, if you’re creating on-line assist, you do want two separate subjects, one for telling customers the way to entry and use the Filter dialog field and the opposite for the Filter dialog itself. One is within the index below Controls, filtering when you map the opposite matter to the button on the Filter window. Give it some thought.
The actual good thing about utilizing the topic-based authoring is that you’ll be able to leverage most on-line assist subjects for any print paperwork which can be required. You get one matter, clear, concise for the reader and a number of outputs for the corporate. Meaning a number of bang on your buck.
Subsequent time: Single-Supply Authoring