Writing Stack Exchange
Writing Stack Exchange

Questions tagged [user-guides]

This tag should be used for questions about creating a guide that is supposed to help users understand something, such as questions about the typical language used in such documents or questions about tools and software that can support the creation of such as document.

This tag should be used for questions about creating a guide that is supposed to help users understand something, such as questions about the typical language used in such documents or questions about and that can support the creation of such as document.

16 questions
15
votes
4 answers

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

The end user documentation I'm writing makes use of screenshots (and partial screenshots) to show the user what I'm referring to in procedural instructions or conceptual explanations of the software. However, I'm never quite sure whether to put the…
Matthew Rodatus
  • 253
  • 2
  • 5
14
votes
2 answers

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

I'm having trouble finding and sticking to one word to indicate whatever value the user intends to use with my instructions. For example: Select your preferred printer. I'm wondering what synonyms for "preferred" you would use in such a…
Pierce Devol
  • 291
  • 1
  • 12
14
votes
3 answers

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

Manuals come with virtually any appliance, and they typically target the end-user. Among other things (legal specifications, part numbers…), these documents contain specific instructions on what to do and what not to do with the appliance. Should…
Philipp
  • 505
  • 5
  • 11
11
votes
6 answers

Demo data in screenshots! What are the best practice?

My question is related to best practices of making screenshots for end-user documentation. Particularly, is there universal information for filling in forms in the software and after that making screenshots. I mean demo data, such as Name, Company…
Yuliya Drygybka
  • 111
  • 1
  • 1
  • 3
10
votes
4 answers

Should user manuals be organized by feature or process?

We have developed a software package and need to write a user manual. I'm trying to determine if the manual should be approached from the perspective of "process" (i.e. accomplishing specific business tasks) or "features" (i.e. the different parts…
RHarris
  • 203
  • 1
  • 3
9
votes
2 answers

How should I document a database schema?

I am going to be writing some user-facing documentation for a database that visitors can query. That is, the people writing queries are not the ones who created the database; they can come in, look at what the database offers, and write their SQL…
Monica Cellio
  • 21,489
  • 3
  • 68
  • 110
8
votes
1 answer

Format keyboard keys in documents

I'm writing a guide to give step-by-step instructions to complete some tasks on the computer. At some points, I need to indicate pressing keys on the keyboard; how may I format the letter/symbol to best indicate them as keys?
Oxwivi
  • 205
  • 1
  • 2
  • 5
8
votes
3 answers

Best Tool to Create User Guides

We are planning to create a user guide for internal use only. It's 150-page document in Word for a self-developed SW tool. The user guide will require constant update. No translation is needed. We would like to have - an easy-to-use interface for…
xifeng
  • 81
  • 2
7
votes
2 answers

Standards for representing user interaction

I am responsible for developing internal IT documentation but have only begun my scratching the surface on technical documentation. Is there a standard or best practice for the following: Example 1: Go to File > Preferences Example 2: Go to the…
ginag
  • 73
  • 3
7
votes
1 answer

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

I'm tasked with rewriting an entire user guide that hasn't been updated for years at a company and I am the only technical writer on the team. Only release notes were sent out all these years. The company adopts the agile development process, and a…
john_doe
  • 173
  • 3
6
votes
1 answer

Is there a style / terminology guide for Android OS application documentation?

This relates to my earlier question: Habits and routines for my first tech writing job I will be involved with writing documentation for an Android OS business application. Is there an Android style guide for this kind of documentation? I really…
Pitarou
  • 267
  • 1
  • 7
6
votes
3 answers

Formatting of Text in Technical Writing (Procedure Writing)

In a procedure, when describing a UI component, we use the bold font to represent UI components. We also match the text with the letter case of the UI component. But do we need to match the font style too? For example, if the UI component is in…
Krishna Baboor
  • 61
  • 2
6
votes
2 answers

Present tense in user manuals

I am writing a user manual for an IT system. And inside the user manual I have sentences such as: Users can delete Servers that do not have Customers assigned to them. Is the use of present-tense verbs such as "do" and "does" considered a…
John John
  • 171
  • 1
  • 3
3
votes
1 answer

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

Background I'm working as a technical writer on a software project where there are three related documents: a user guide, a Python API reference and a C++ API reference. The user guide describes how to use the classes, methods, and so on and then…
JaynieP
  • 33
  • 3
1
vote
2 answers

How can I make the process of writing easier?

I came up with an AI image generation party game, and I wanted to tell about it to others. It took me an hour to write the description, even though I already knew all the details in my head. It was very hard to write it, I didn't know what order to…
curiousCprogrammer1231
  • 31
  • 1
1
2