Writing style guidelines

[dngray]

To make Privacy Guides a high quality resource I propose that we have some guidelines, that how content should be presented.

I like having advanced articles of the site, but I think needs to be a bit like an onion, in respect to being able to peel off entry level layers and get some usefulness out of it without being bombarded with very in-depth specifics that might turn off new readers.

This would allow for entry level articles to self cite more complex reasoning, for issues discussed.

I described that in https://github.com/privacyguides/privacyguides.org/issues/834#issuecomment-1087354314

We might want to get a guideline, this is a good one I think https://www.gov.uk/guidance/content-design/writing-for-gov-uk.

I think in general this would be an improvement, as it would prevent highly specific information being on the surface https://github.com/privacyguides/privacyguides.org/pull/904/files/7be16078d8d7e6fb8eb0469fb59da210dac7dbc1#r842391988

This issue is one i want to get codified before we begin outreach for translations https://github.com/privacyguides/privacyguides.org/discussions/30

I think it will help translators a lot.

[TommyTran732]

The page is extremely inconsistent. Should additional information be inside of the cards like the Android or Linux page or by inside of the cards like the rest of the site?

I think its best to just do it like the Android/Linux page, so we can have a brief discussion in the card, but more in depth information can be put outside the card and the user can ignore what's outside of the cards if they are not interested.

[freddy-m]

Would this require a style guide?

[jonaharagon]

I think its best to just do it like the Android/Linux page

Yes 👍

[jonaharagon]

https://www.plainlanguage.gov/guidelines/ is a similar set of guidelines in American English.

[elitejake]

Also check out Wikipedia''s Manual of Style. Their abbreviations style conventions and make technical articles understandable guide is pretty useful. Suggestion: we should make use of the <abbr> tag.

[razac-elda]

After a quick look at those guidelines I think @elitejake found the right one, the UK and US ones are good for general article advice. Wikipedia introduces concepts for more advanced styles and, being a widley popular website, users will find it more familiar to read.

[dngray]

Another one that wouldn't hurt is:

• https://docs.microsoft.com/en-us/style-guide/procedures-instructions/writing-step-by-step-instructions
• https://docs.microsoft.com/en-us/style-guide/procedures-instructions/describing-interactions-with-ui

[elitejake]

We shouldn't follow these guidelines as-is, because they don't make use of Markdown.

For example, Microsoft's guide state that we should use bold text for commands instead of code blocks.

[qua3k]

is this the right place to ask for line wrap please

[dngray]

is this the right place to ask for line wrap please

Been thinking about that myself actually. I'm actually not sure why we never did do line wrapping

[jonaharagon]

I would be extremely against traditional hard-wrapping at an arbitrary set column size, but I'd consider reformatting to one sentence per line if we wanted, which would probably have great VCS benefits for our Git-oriented workflow as a bonus.

Another thought on the plain-text readability side of things, we probably should consider reference-style links rather than inline links, for all of our links but especially duplicate links on the same page.

[ghost]

I think we should try to avoid using "user/users" for more descriptive terms. As far as I know, this is what most companies with documentation writing styles practice. Relevant discussion: #1080

I found the GitHub Explore style guide to be laid out nicely. Could be used for some inspiration.

[dngray]

I think we should try to avoid using "user/users" for more descriptive terms. As far as I know, this is what most companies with documentation writing styles practice. Relevant discussion: #1080

Only exception to this would be where it relates to some terminology. so "user permissions" for example. So this rule applies to where we refer to our readers as users, that's what we should avoid doing.

[jonaharagon]

In response to my own comment https://github.com/orgs/privacyguides/discussions/1080#discussioncomment-2619033:

Then we would need to determine the formality of the site's writing, whether we should stick with third-person or use words like "you"

I think referring to the reader directly is a good thing, we're giving advice to people, not writing an academic study of these tools. I'm working on a PR replacing "user" language now.

[jonaharagon]

Started drafting a page at https://github.com/privacyguides/privacyguides.org/wiki/Writing-Style

Standardizing on:

• American English
• plainlangauge.gov guidelines for writing and tone
• APA Style rules for grammar and style

[matchboxbananasynergy]

Checking in here; is there more work to be done to finalize the writing style guide, or is this issue good to be closed?

[jonaharagon]

I think we can work out details separately, this is basically done.