Quick Advice

The full technical writing reference is extensive — and also long. There are a few handy habits that could help you to write solid texts, even if they do not necessary follow the guide.

If you are stuck with a single prompt that just does not look right, leave it alone and finish the rest of the article. Leave it for tomorrow, if you must. Your brain will find a way to rewrite it, or you will find out that you can just remove the troubled piece.

Read your text out aloud. As silly as it sounds and as silly as you sound, this reveals most issues with the current revision. Misspelled or skipped words become apparent, some prompts sound confusing with missed context or hang in the air without a proper ending or follow-up. You stop to draw breath in the middle of an overly long sentence, and a paragraph with too many hard breaks makes you stutter.

If you have troubles writing the first paragraph, write any sort of introduction or start writing from the middle. Starting is the hardest part, and you will always have a chance to cut trivialities or elaborate when you get momentum.

If nothing helps, put the article to review as it is and mention your issues in the pull request. Others might give you an idea.

You can break any rule as long as your take does the job better.