Tip 37 - right words, wrong place
Lots of docs writing tips focus on specific word usage: use them correctly; use more precise words; use fewer of them! Sometimes, our words are already pretty good.
We canât get complacent, though! Sometimes writing that would fit very well in one place of your documentation doesnât quite work in another.
One PR suggestion I often make doesnât significantly change words, but rearranges them to align with the purpose of the content. Writing may be clear, correct, and even helpful, but presented at the wrong time. The example below is going to need some context to show why I prefer one over the other. Otherwise, itâs difficult to tell!
The examples below occur immediately after a heading called âSetupâ and the reader is assumed to be staring at a new, blank project.
-
â Astro starter projects include a
tsconfig.json
file in your project. This file is important so that tools like Astro and VS Code know how to understand your project. Some features (like npm package imports) arenât fully supported in the editor without atsconfig.json
file. If you install Astro manually, be sure to create this file yourself. -
đ Astro always treats your component code as TypeScript, but some features (like npm package imports) arenât fully supported in the editor without a
tsconfig.json
file. Even if you donât write TypeScript, this file is important so that tools like Astro and VS Code know how to understand your project. Astro starter projects include this file, but if you install Astro manually, be sure to create it yourself.
The difference is subtle, but I think it exists. In this situation, I prefer to first call attention to the file itself. In fact, I do like the nuance that âAstro treats your code as TypeScriptâ (even if you only write JavaScript). In another context, itâs a great lead-in! I would totally use it to set a stage, just not this stage.
We wouldnât list steps out of order. (Well, we wouldnât do that. đ ) A sequence of concrete steps, like a set of instructions, gives us a natural structure to follow in our writing. Absent that, we have to do the heavy lifting ourselves to structure our (good) content in the context of the readerâs journey through our docs, and the purpose of each page.
Toggle Comments
© 2021 - 2024 Sarah Rainsberger. Except where otherwise noted, and/or quoting external sources, the content of this site is licensed under CC BY-NC-SA 4.0