2

In technical writing, it is common to use so-called admonitions, also known as notices: see "Notes, cautions, warnings, and other notices" in the style guide for technical writers by Google, for example.

The names of these admonitions may vary, but the most often used ones are Note, Warning, and Tip. From which, Note is the very most often used one.

The problem is that, as far as I know, if a book contains endnotes, they should be listed in the "Notes" section.

And so we have notes in the text itself as admonitions, and notes in the "Notes" section. This doesn't look good. Any ideas on how to work around this issue?

2
  • 2
    Are you writing a book? If so, why are you referring to a style guide for websites (Google Developers)?
    – Laurel
    Aug 30, 2022 at 18:09
  • If something is a serious warning then it's better to label it CAUTION or WARNING. But if you must follow the Google documentation, what does it say about citing references?
    – Stuart F
    Sep 5, 2022 at 16:10

1 Answer 1

2

A few things.

  1. The style guide you linked does not treat the different admonition words as interchangeable. Each has a specific use-case within the style guide. I also could not find anything in Google's style guide about end notes, so if you're following Google's guide consistently, then you shouldn't have any concerns.

  2. Style guides are not definitive authorities on how something should be done, they're guides. If you choose not to follow the guide then its conventions don't matter. That said, style guides are commonly recommended, or even required, in academic or business settings, so if you're told explicitly to use a guide or manual then you're bound to its rules. But if you're not explicitly following the Google style guide, then its conventions for admonitions have no authority over your writing. You're free to use "note" however you like.

  3. Even if nobody is requiring you to use a style guide that doesn't mean you shouldn't use one. They are useful for resolving issues like the one you've talked about, where you're unsure of how to structure or label parts of your writing. If you do choose to follow a style guide or manual, follow it completely, don't do half-measures. This is a benefit to your readers. Consistently following a guide lets them know what set of conventions you're adhering to.

  4. If you choose not to follow a guide then don't get so hung up on terminology. You can call your end notes whatever you want, or your admonitions whatever you want, though I'd hope you're at least consistent and intuitive with your naming scheme. As to whether or not this is advisable, that depends on who you're writing for. What does your audience expect or demand of you? I think in most cases, you're best off following what I said in point 3, but it is ultimately up to you.

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.