24
If a reader follows a reasonable path1 through your documentation, there should never be a point where he's looking at something incomprehensible. This applies to text, code samples, diagrams...and screen shots. Therefore, unless the structure of your document itself provides this (e.g. through section titles and a consistent format, like in a catalogue), ...
19
One possibility is to not use the adjective: "Select a printer".
Another is to use the adjective appropriate to the action: Sometimes you mean "Select a disk", sometimes (like for formatting) you mean "Select the target disk", sometimes (for installing an OS) "Select the desired boot disk", etc.
I wouldn't look for just one word. "Preferred" is sometimes ...
16
Use direct, simple, clear, imperative instructions.
Passive voice and subjunctive make your language unclear and complicated for an international audience. Luckily in this respect there is no argument among the various schools of thought. For details, peruse the following style guides. Both make very instructive reading.
The IBM Style Guide is my reference ...
12
Let's break down your illustrative sentence:
Users can delete Servers
This statement describes a capability -- users can perform this action. I'm hard-pressed to imagine how a different tense could be used here. Some technical writers (or style guides) make this overly passive -- "the system supports user deletion of servers" or some such. Speaking ...
12
For internal documentation I've found wikis to be quite useful. A wiki has several useful features for this task:
built-in change-tracking
doc can be structured as several pages (e.g. one per major section) for easier management; individual pages can then be edited without any need to merge changes into a master document
some (most?) wiki platforms detect ...
10
All instructions writers wrestle with these terms. Just remember that instructions should be absolutely clear, without ambiguity. "Preferred" can be ambiguous. Does a "preferred" printer stay that way? Are you referring to a "preferred" printer, or just a printer to use now?
Select the printer to use (for whatever you are doing).
Avoid "desired" and ...
8
Some writers use these situations as an opportunity to embed small "Easter eggs," targeting your audience. For example, if your audience is in the UK and "geeky," Doctor Who references could work. In Australia, Mad Max references could work.
This solution is not for everyone, but my usual developer audiences appreciate them, so long as they're subtle.
8
Assuming native speakers of American English:
For first names:
John
Jack
Mary
Jane
For last names:
Doe
Smith
Jones
Johnson
Full names:
John Doe is native English shorthand for "generic person."
Richard Roe is native English legal shorthand for "second generic person in the same document as John Doe." ["Jane Roe" (an anonymous woman at the time) is the ...
answered Jun 18 '13 at 11:47
Lauren-Clear-Monica-Ipsum
74.1k7 gold badges117 silver badges256 bronze badges
8
If this is user-facing documentation, then make up a data dictionary that describes the tables and columns with supplementary blurbs about the meaning of the data (e.g. the meanings of specific values in a column). This can be a straightforward HTML document with the supplementary descriptions as text.
If you need to produce E/R diagrams then Visio ...
7
Passive voice gets a bad reputation. We're taught to avoid it at all costs. For the most part that's correct, too. It's dull, slows the sentence, and is often vague. If you're writing end user documentation, you should have a style guide and follow it. There's nothing wrong with active voice and even using "you" as long as it's the style you want, along with ...
7
I am assuming that your organization does not have an official style guide, or that this is a personal project. (If you are bound by a style guide, consult it.) I am also assuming that you aren't using a semantic markup already; if you're using a DTD/schema/tool/markdown that already has a notion of "keyboard input", you'd use that unless there's a good ...
6
I've written manuals under a Scrum process, so I'll describe what worked for my team.
I'm going to treat your task as if you're writing a new book. From your description, you'd be replacing the vast majority of the content anyway, so better to think of it as a new book (for which you might be able to take advantage of the occasional previously-written bit) ...
5
In most cases, I think, it is best to organize an end-user manual by process because this is what the user cares about. When they use the software they will begin with the first step of their workflow and work according to their process. Complex processes can be divided into smaller sub-processes. The manual's outline will then follow their progress. Users ...
5
The standard I found most common and probably most clear is to quote anything that appears on screen as fixed-width font on grey background. Using unicode right arrow → is the neat, elegant way to shortcut a traverse through interface.
Open File → Preferences and pick the Advanced tab.
Use the slider to adjust Allocated memory to 30MB and confirm with [OK].
...
4
1) Put the descriptive text first, then the screenshot immediately afterwards. We read down.
In the Print dialog box, click Export to PDF.
[SCREENSHOT of dialog box]
2) You may or may not need a caption, but you should at least label each screenshot. Fig. 1, Screen B, Ralph, something. That allows you to refer to it elsewhere in the text.
answered Jun 14 '13 at 14:16
Lauren-Clear-Monica-Ipsum
74.1k7 gold badges117 silver badges256 bronze badges
4
I will echo Matt in suggesting that the process orientation is the best approach.
However, let me propose a hybrid approach. The software might support multiple processes and those processes might share functional steps. Duplicating the documentation for those shared steps (especially if the steps are complicated) is not a good idea. It is better to document ...
4
Typically in documentation you would want every UI reference to be styled consistently. This would lead me to think that matching font styles to individual elements is not the ideal approach.
Best practice would be to create a style guide that includes how you are going to indicate a UI element, and adhere to that in all cases. This will help your audience ...
4
These are style questions and mostly a matter of opinion; but if the matching is intended to help the user recognize the key, then if I were writing a manual I would match the italics, and if possible the font as well.
I presume by "procedure" you do not mean code, but a recipe of action for a human operator to accomplish some goal or outcome.
3
It depends on your audience.
Blessed Geek suggested UML enumeration, but this assumes that the users understand UML. Your question shows that you know technology well enough to know the capabilities of your users.
Writers often use Javadoc or Doxygen to generate API documentation because those tools easily generate new docs when the API itself changes. ...
3
My previous company faced this issue in many situations. They handled it in several ways:
The company registered a domain name, so that we could use it as an example domain in URLs.
For names, we used characters from famous works of fiction. My favorite was Elizabeth Bennett. I also used famous authors, like Emily Dickinson.
For addresses, I used the street ...
3
Take great care when you opt to use a single generic name (or even a limited set). What is the message you are sending to Trang, Luigi and Antwan when every reference to a given name uses John or Richard?
Are you certain that your target audience is so ethnically homogeneous that they will all identify with Dick and Jane from Picket Fence Lane in Smalltown? ...
3
I mostly agree with Lauren Ipsum, just a couple of extra thoughts:
As Lauren says, John Doe and Jane Doe are widely recognized as fake names.
John Q Customer is often used for a fake customer name.
For US telephone numbers, use "555" for the exchange, like "123-555-1234". "555" is reserved by the phone companies just for use in examples and in books and ...
2
Screenshots can also come to the right or left of text that references them. Using columns can improve readability and keep illustrations from being separated across pages from the text that references them.
2
An introductory text should always come before the screenshot that you are about to display. This will help the user to get an idea of what is about to be displayed in the screenshot.
Then you can definitely provide the descriptive text for what exactly is happening in the screenshot for better understanding of the user.
2
In the past, I've used a wiki for this type of work. However, a tool doesn't organize itself. The best wiki sites are heavily edited from every level from copy to development.
2
I would rewrite that sentence completely as:
You may delete servers that do not have customers assigned to them.
Note that I also removed the unnecessary capitaliztion.
2
A good resource for this is:
the Microsoft Manual of Style (the 4th edition is available via bookstores, older versions can be found on the internet as PDF or Winhelp file).
@SF's answer pretty much matches this style guide.
Whichever convention you end up using: document it. Add a section 'About this document' where you explain what your conventions mean.
...
2
Why not both?
In the Olden Days™, software would often come with two sorts of documentation:
A tutorial or user guide, explaining how to perform common tasks. This could be anything from a quick getting-started guide, up to a comprehensive list of tasks you might want to perform.
A reference manual, giving details of all the software's functions. It ...
1
I’ve never heard of issues caused by overciting, but underciting causes many problems.
When in doubt, cite it — if nothing else it lends credibility if you can cite reputable sources for any facts you include — it helps show you are aligned with standard practices in a field.
I’d recommend footnotes plus an appendix of works cited and further reading.
Only top voted, non community-wiki answers of a minimum length are eligible
