3 ms·
Writing clearly and concisely is not easy, so it's quite natural for many people to find it difficult. In fact, writing woolly and verbose prose is much easier
by open-source-ux 6y ago
Writing clearly and concisely is not easy, so it's quite natural for many people to find it difficult. In fact, writing woolly and verbose prose is much easier - perhaps why it's so predominant?
Practice will help. Reading other people's writing will also help - find examples of writing you like.
Most product documentation is abysmal. Here is a random, but reasonably good example: installation instructions for Craft CMS. It assumes some technical knowledge, but the description is fairly clear: https://docs.craftcms.com/v3/installation.html https://docs.craftcms.com/v3/installation.html
I find the 10 tips for clear writing at the following link very helpful:
https://gds.blog.gov.uk/2019/08/27/podcast-on-writing/ https://gds.blog.gov.uk/2019/08/27/podcast-on-writing/
You don't need to listen to the podcast (unless you want to) at the top of the linked page. Scroll down the page and you'll find a short description of each of the following tips:
1. Establish ‘The Point’
2. Write it like you’d say it
3. Don’t try to sound clever
4. Show the thing
5. Know that you are not your writing
6. Share your work
7. Read (poetry in particular)
8. Never start with a blank page
9. Know when enough is enough
10. Stay human
Edit: another example I wanted to share of clear writing. The NHS (National Health Service in the UK) has an excellent A-Z of health conditions website: https://www.nhs.uk/conditions/ https://www.nhs.uk/conditions/
I have always liked how clear, straightforward and simple the entries are without the information being 'dumbed down' in any way. Here is a random health entry (on epilepsy) to illustrate: https://www.nhs.uk/conditions/epilepsy/ https://www.nhs.uk/conditions/epilepsy/