Align writing tips with readability guidelines

thegooddocsproject / templates

Templates created by The Good Docs Project - for all your tech writing needs.

https://thegooddocsproject.dev/

Other

679 stars 170 forks source link

Align writing tips with readability guidelines #65

Open camerons opened 4 years ago

camerons commented 4 years ago

Re: https://github.com/thegooddocsproject/templates/blob/master/writing-tips.md

Michelle Mortimer 14:24 14 Nov It would be great to sync up in some way with Sarah Richards' readability guidelines project. Can we strive towards one source of truth for readability, style, formatting, accessibility etc? I can see these 'universal' doc templates as a powerful part of that https://contentdesign.london/usability/readability-guidelines/

camerons commented 4 years ago

Josh Sherwood 14:17 14 Nov I love the idea of this page as a 'If you don't read anything else, read this!' page – I think it could be even further simplified to include only the general principles for writing that could then be delved into deeper if the reader a) has time and b) can be bothered.

camerons commented 4 years ago

Erin McKean 13:40 14 Nov suggestion from Ross [Johnson?]: add section about figuring out who your audience is first. [before Language and Tone]

Dylan Lacey 13:39 14 Nov Is Intended Audience something that should come first?

Dishebh commented 4 years ago

@camerons I want to work on the issue. Just a couple of thoughts:

Are we following the Google style guide or the guidelines of Content Design London? If we take some from former and a bit from later source currently, won't it make the docs less consistent than what it is now?
Also, don't we know who the target audience is, already? (from the point mentioned below)

Follow these writing guidelines when developing content using the templates available in this repository.

I also see some inconsistencies in this doc, like tool Vale is encapsulated within the template strings whereas tool Grammarly isn't. Shall I go ahead and correct these, first?

camerons commented 4 years ago

Michelle has raised a point which I think would be useful for a wider discussion. @Dishebh I suggest this is probably not a good starter issue to work on.