Skip to main content

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.

Filter by
Sorted by
Tagged with
2 votes
2 answers
114 views

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 ...
curiousCprogrammer1231's user avatar
3 votes
1 answer
30 views

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 ...
JaynieP's user avatar
  • 33
10 votes
4 answers
498 views

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 ...
RHarris's user avatar
  • 203
0 votes
1 answer
42 views

When is it appropriate to include citations in a guidebook?

I'm working on a series of self-published guidebooks aimed at teaching tech skills for people who aren't tech literate. My only prior experiences writing nonfiction have been research papers for ...
VoxxSkies's user avatar
15 votes
2 answers
999 views

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 ...
Pierce Devol's user avatar
6 votes
3 answers
500 views

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 ...
Krishna Baboor's user avatar
14 votes
3 answers
656 views

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 ...
Philipp's user avatar
  • 505
8 votes
1 answer
2k views

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 ...
Oxwivi's user avatar
  • 205
9 votes
2 answers
6k views

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 ...
Monica Cellio's user avatar
7 votes
1 answer
321 views

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 ...
john_doe's user avatar
  • 173
8 votes
3 answers
1k views

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 ...
xifeng's user avatar
  • 81
6 votes
2 answers
5k views

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-...
John John's user avatar
  • 171
7 votes
2 answers
184 views

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:...
ginag's user avatar
  • 73
11 votes
6 answers
10k views

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 ...
Yuliya Drygybka's user avatar
15 votes
4 answers
5k views

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. ...
Matthew Rodatus's user avatar
6 votes
1 answer
2k views

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 ...
Pitarou's user avatar
  • 267