19 votes
Accepted

Preferred word for "preferred", "target", "chosen" in end user support documentation

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 ...
user avatar
  • 92.1k
16 votes
Accepted

Instruction manuals: should the end-user be addressed directly (passive vs imperative)?

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 ...
user avatar
12 votes

Best Tool to Create User Guides

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 ...
user avatar
10 votes

Preferred word for "preferred", "target", "chosen" in end user support documentation

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?...
user avatar
  • 1,250
8 votes

How should I document a database schema?

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 ...
user avatar
7 votes

Instruction manuals: should the end-user be addressed directly (passive vs imperative)?

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 ...
user avatar
7 votes
Accepted

Format keyboard keys in documents

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 ...
user avatar
6 votes
Accepted

How do I approach rewriting an entire user guide in an agile environment?

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 ...
user avatar
5 votes
Accepted

Should user manuals be organized by feature or process?

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 ...
user avatar
  • 663
4 votes

Should user manuals be organized by feature or process?

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 ...
user avatar
  • 4,904
4 votes

Formatting of Text in Technical Writing (Procedure Writing)

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 ...
user avatar
  • 123
4 votes

Formatting of Text in Technical Writing (Procedure Writing)

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 ...
user avatar
  • 92.1k
3 votes

Demo data in screenshots! What are the best practice?

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 ...
user avatar
  • 249
3 votes

How should I document a database schema?

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 ...
user avatar
  • 249
2 votes

Best Tool to Create User Guides

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.
user avatar
  • 249
2 votes

In end user documentation, should screenshots come before or after the text that references them?

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 ...
user avatar
  • 1,250
2 votes

Should user manuals be organized by feature or process?

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 ...
user avatar
  • 601
1 vote
Accepted

What are the conventions for formatting links to two API references in software user guide text?

So a common technique I have found is for online or digital documentation, to offer the information for the different languages as a selectable dropdown or tabbed panel in some way. Either as a tabbed ...
user avatar
1 vote

When is it appropriate to include citations in a guidebook?

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 ...
user avatar
  • 111
1 vote

Instruction manuals: should the end-user be addressed directly (passive vs imperative)?

Recently, my favorite documentation style is the one promoted by the Pragmatic Bookshelf, a major technical publisher. The PB authors must structure their books as conversations with their prospective ...
user avatar
  • 373
1 vote

Demo data in screenshots! What are the best practice?

You can use Sherlock Holmes, since he is a public domain fictional character and he has a famous fictional address. I think this adds a little fun but not so much that it is distracting, and it feels ...
user avatar
  • 1,348

Only top scored, non community-wiki answers of a minimum length are eligible