0

Section 2.3: Quirks

Relative paths are displayed as absolute

Example:

  1. Tools > Options > Load/Save > General > Save URLs relative to file system = True
  2. Insert a linked image (Insert > Image > Link = True), open its preferences window, select the Image tab, and note that the path in the File name field is displayed as absolute.

The text above is from a software manual I'm working on. The list is essentially an example, but I'm not sure the word "example" is really appropriate there.

What is called "paths" can be used not only for images, but also for text files, audio/video, document fragments, and so on. And my list illustrates only a single case: images.

How to properly introduce it for the reader?

5
  • Is the example not an example? You could simply add a sentence under (2) saying "This also applies to [list of other cases]".
    – Andrew Leach
    Oct 16, 2021 at 22:23
  • Andrew, there is a small problem with this solution. The manual is full of how-to instructions, which look exactly the same, as a numbered list. And so when the user will see this one list, he (or she) will need some additional time to figure out that it is in fact something different in its nature.
    – user90726
    Oct 16, 2021 at 22:32
  • 1
    In that case, it's using the numbered list which is wrong rather than the word Example. (1) is "Setting" and (2) is "Observed quirk" The list entries probably don't need numbers or titles at all. I'm not sure you can improve on the word "Example." But perhaps it is possible: let's see what others come up with.
    – Andrew Leach
    Oct 16, 2021 at 22:40
  • Andrew, could you explain why you think the numbered list is wrong? I'm trying to understand your idea better.
    – user90726
    Oct 16, 2021 at 23:24
  • The numbered list is the wrong thing to use because it's not a "How-to" list of instructions in the same way as your other lists. You're not explaining how to do something the user wants to achieve.
    – Andrew Leach
    Oct 17, 2021 at 7:35

1 Answer 1

1

How about "Exercise (Inserting Images)"?

or Lesson instead of exercise, or just keep example but parenthetically append the disclaimer that what's shown is just one example out of other possibilities (i.e., in this case, you've chosen the example of "(Inserting Images)")

It really depends on the precedent you've set in the manual (if you have yet), and the critical thing being that there is unexceptional consistency

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.