Last week I wrote that the purpose of technical writing is to save time and reduce frustration for readers. This week, I'm adding that the primary means for doing that is organizing information effectively.
When I think of information architecture with regard to technical writing, I think of re-organizing information in whatever way would make it easier for the reader to understand and use.
When information is organized well, it's quickly learned and easily remembered. And searching within it seems effortless, because the locations of things are predictable.
Technical writers use information architecture from the level of organizing their thoughts, down to word choices and the order of words.
One article isn't enough space for a complete guide to information architecture. This is more like a handful of examples that demonstrate the idea.
At the big picture level
Information can always be organized in more than one way. Whether you are organizing a site, an article or an API reference collection, the important thing is not to get stuck in one way of seeing the information because you found it that way or because people are used to it. If organizing in a different way would be more useful for the reader, change it.
Sort information by type
When you work on a collection of articles, separate the information readers use for understanding the system from information they use when getting things done. Technical writers often sort information into concepts, tasks, and reference to ensure that readers can find the kind of information they want, and that it doesn't contain information irrelevant to the task at hand.
(See my article about minimum viable documentation for more about the three types of information.)
See things as the reader sees them
Similarly, the outline that you choose should take the reader's point of view. In other words focus on what the reader wants to accomplish and how it looks to the reader, rather than how your system was built or how it functions under the hood. A description of tasks that the reader can do (and how to do them) is more helpful than a detailed anatomical description of the system.
This all applies to API reference docs
Incidentally, these ideas might seem contrary to the way API reference docs are presented, but they aren't.
API reference docs (e.g. Swagger docs) generally exclude anything irrelevant -- long-winded overviews of the product or how-to sequences. If they're well designed, they use terminology that makes sense to the user and have an easy consistency among the parts that make them up. If they're not well-designed, they seem confusing and difficult to use.
A well-designed API is orderly in the same way as a well-developed taxonomy. (Although, a detailed comparison of one to the other will have to wait for another day, because it would be too long to fit here.)
At the middle level
In the body of an article, technical writing has its own data structures to organize information in ways that are easily used.
Bullet points. Use them for unordered lists.
Numbered steps. They're the best way to describe actions have to be performed in a specific order.
Tables. For information that can be sorted categorically. Organize tables into columns and rows according to categories that will make the most sense to the reader. Use table headers that will help readers find and understand relevant information quickly.
Headings and subheadings. They act as signposts for navigating the body of an article more than a few paragraphs long. Keep them short and to the point.
At the sentence level
Even on the simplest level, the sentence, you will find that you need to organize information into structures that make it easier to understand and use.
Parallel construction
Use parallel construction when writing numerous entries that have the same purpose, as in a reference document. There is a design pattern for the summaries and descriptions in an OAS3 spec that goes approximately like this:
verb + noun (+ how)
.
For example:
Retrieves all purchase orders
Retrieves a purchase order by ID
Deletes a purchase order by ID
Think about other places where you can make your documentation easier to read and easier to write by sticking to a standard format for multiple entries.
First things first
When writing numbered steps, remember to also keep things in the right order, within each step. For example: "From the SETUP menu, choose STORAGE." I remember test driving internal docs where an instruction like this was inverted ("Choose STORAGE from the SETUP menu"). Each test user had been proceeding from one bolded choice to the next, and every time someone arrived at this sentence, they said, "Where's storage?" They hadn't opened the SETUP menu yet, because it was the next item they would come to.
Since then, I try to present information in the order it will be needed, even on the sentence level.
Keep it simple
As always, write mostly in short, simple sentences with noun + verb
construction. This is not a structure in itself but it forces you to stick to important facts and it avoids needlessly complex sentence that appear to convey more complicated information but don't. Those sentences tax the reader for no special reason.
Final thoughts
The cardinal sin of technical writing is the copy-paste.
Technical writers don't receive information and pass it along. They digest multiple sources of information and reorganize them into something and more useful.
When you document your application, think about how people will use it, what they will search for, and how they will expect to find things. Start with the information you have and think about how to convert it into the information the user will need.