mirror of
https://github.com/privacyguides/privacyguides.org.git
synced 2024-12-22 06:05:11 -05:00
About category changes (#1875)
Co-authored-by: Freddy <freddy@privacyguides.org> Co-authored-by: matchboxbananasynergy <107055883+matchboxbananasynergy@users.noreply.github.com> Co-authored-by: mfwmyfacewhen <94880365+mfwmyfacewhen@users.noreply.github.com> Co-authored-by: Kai Tebay <95620167+KaiTebay@users.noreply.github.com>
This commit is contained in:
Jonah Aragon
GitHub
parent
b20785b3b6
commit
4f8663321a
@ -1,15 +0,0 @@
|
||||
---
|
||||
title: "About Privacy Guides"
|
||||
---
|
||||
|
||||
**Privacy Guides** is a socially motivated website that provides information for protecting your data security and privacy. We are a non-profit collective operated entirely by volunteer team members and contributors.
|
||||
|
||||
Our current list of team members can be found [here on GitHub](https://github.com/orgs/privacyguides/people). Additionally, [many people](https://github.com/privacyguides/privacyguides.org/graphs/contributors) have made contributions to the project. You can too, we're open sourced on GitHub!
|
||||
|
||||
Our team members review all changes made to the website and handle administrative duties such as web hosting and financials, however they do not personally profit from any contributions made to this site. Our financials are transparently hosted by the Open Collective Foundation 501(c)(3) at [opencollective.com/privacyguides](https://opencollective.com/privacyguides). Donations to Privacy Guides are generally tax deductible in the United States.
|
||||
|
||||
*The following is a human-readable summary of (and not a substitute for) the [license](https://github.com/privacyguides/privacyguides.org/blob/main/LICENSE):*
|
||||
|
||||
:fontawesome-brands-creative-commons: :fontawesome-brands-creative-commons-by: :fontawesome-brands-creative-commons-nd: Unless otherwise noted, the original content on this website is made available under the [Creative Commons Attribution-NoDerivatives 4.0 International Public License](https://github.com/privacyguides/privacyguides.org/blob/main/LICENSE). This means that you are free to copy and redistribute the material in any medium or format for any purpose, even commercially; as long as you give appropriate credit to `Privacy Guides (www.privacyguides.org)` and provide a link to the license. You may do so in any reasonable manner, but not in any way that suggests Privacy Guides endorses you or your use. If you remix, transform, or build upon the content of this website, you may not distribute the modified material.
|
||||
|
||||
This license is in place to prevent people from sharing our work without giving proper credit, and to prevent people from modifying our work in a way that could be used to mislead people. If you find the terms of this license too restrictive for the project you're working on, please reach out to us at `jonah@privacyguides.org`. We are happy to provide alternative licensing options for well-intentioned projects in the privacy space!
|
||||
40
docs/about/criteria.md
Normal file
40
docs/about/criteria.md
Normal file
@ -0,0 +1,40 @@
|
||||
---
|
||||
title: General Criteria
|
||||
---
|
||||
|
||||
!!! example "Work in Progress"
|
||||
|
||||
The following page is a work in progress, and does not reflect the full criteria for our recommendations at this time. Past discussion on this topic: [#24](https://github.com/privacyguides/privacyguides.org/discussions/24)
|
||||
|
||||
Below are some things that must apply to all submissions to Privacy Guides. Each category will have additional requirements for inclusion.
|
||||
|
||||
## Financial Disclosure
|
||||
|
||||
We do not make money from recommending certain products, we do not use affiliate links, and we do not provide special consideration to project donors.
|
||||
|
||||
## General Guidelines
|
||||
|
||||
We apply these priorities when considering new recommendations:
|
||||
|
||||
- **Secure**: Tools should follow security best-practices wherever applicable.
|
||||
- **Source Availability**: Open source projects are generally preferred over equivalent proprietary alternatives.
|
||||
- **Cross-Platform**: We typically prefer recommendations to be cross-platform, to avoid vendor lock-in.
|
||||
- **Active Development**: The tools that we recommend should be actively developed, unmaintained projects will be removed in most cases.
|
||||
- **Usability**: Tools should be accessible to most computer users, an overly technical background should not be required.
|
||||
- **Documented**: Tools should have clear and extensive documentation for use.
|
||||
|
||||
## Developer Self-Submissions
|
||||
|
||||
We have these requirements in regard to developers which wish to submit their project or software for consideration.
|
||||
|
||||
- Must disclose affiliation, i.e. your position within the project being submitted.
|
||||
|
||||
- Must have a security whitepaper if it is a project that involves handling of sensitive information like a messenger, password manager, encrypted cloud storage etc.
|
||||
- Third party audit status. We want to know if you have one, or have one planned. If possible please mention who will be conducting the audit.
|
||||
|
||||
- Must explain what the project brings to the table in regard to privacy.
|
||||
- Does it solve any new problem?
|
||||
- Why should anyone use it over the alternatives?
|
||||
|
||||
- Must state what the exact threat model is with their project.
|
||||
- It should be clear to potential users what the project can provide, and what it cannot.
|
||||
67
docs/about/index.md
Normal file
67
docs/about/index.md
Normal file
@ -0,0 +1,67 @@
|
||||
---
|
||||
title: "About Privacy Guides"
|
||||
---
|
||||
|
||||
**Privacy Guides** is a socially motivated website that provides information for protecting your data security and privacy. We are a non-profit collective operated entirely by volunteer [team members](https://discuss.privacyguides.org/g/team) and contributors.
|
||||
|
||||
## Our Team
|
||||
|
||||
??? person "@jonah"
|
||||
|
||||
- [:simple-discourse: Discourse](https://discuss.privacyguides.org/u/jonah)
|
||||
- [:simple-github: GitHub](https://github.com/jonaharagon "@jonaharagon")
|
||||
- [:simple-mastodon: Mastodon](https://aragon.sh/@jonah "@jonah@aragon.sh"){rel=me}
|
||||
- [:fontawesome-solid-house: Homepage](https://www.jonaharagon.com)
|
||||
|
||||
??? person "@niek-de-wilde"
|
||||
|
||||
- [:simple-discourse: Discourse](https://discuss.privacyguides.org/u/Niek-de-Wilde)
|
||||
- [:simple-github: GitHub](https://github.com/blacklight447 "@blacklight447")
|
||||
- [:simple-mastodon: Mastodon](https://mastodon.social/@blacklight447 "@blacklight447@mastodon.social"){rel=me}
|
||||
|
||||
??? person "@dngray"
|
||||
|
||||
- [:simple-discourse: Discourse](https://discuss.privacyguides.org/u/dngray)
|
||||
- [:simple-github: GitHub](https://github.com/dngray "@dngray")
|
||||
- [:simple-mastodon: Mastodon](https://mastodon.social/@dngray "@dngray@mastodon.social"){rel=me}
|
||||
- [:fontawesome-solid-envelope: Email](mailto:dngray@privacyguides.org)
|
||||
|
||||
??? person "@freddy"
|
||||
|
||||
- [:simple-discourse: Discourse](https://discuss.privacyguides.org/u/freddy)
|
||||
- [:simple-github: GitHub](https://github.com/freddy-m "@freddy-m")
|
||||
- [:simple-mastodon: Mastodon](https://social.lol/@freddy "@freddy@social.lol"){rel=me}
|
||||
- [:fontawesome-solid-envelope: Email](mailto:freddy@privacyguides.org)
|
||||
- [:fontawesome-solid-house: Homepage](https://freddy.omg.lol)
|
||||
|
||||
??? person "@mfwmyfacewhen"
|
||||
|
||||
- [:simple-discourse: Discourse](https://discuss.privacyguides.org/u/mfwmyfacewhen)
|
||||
- [:simple-github: GitHub](https://github.com/mfwmyfacewhen "@mfwmyfacewhen")
|
||||
- [:fontawesome-solid-house: Homepage](https://mfw.omg.lol)
|
||||
|
||||
??? person "@matchboxbananasynergy"
|
||||
|
||||
- [:simple-discourse: Discourse](https://discuss.privacyguides.org/u/matchboxbananasynergy)
|
||||
- [:simple-github: GitHub](https://github.com/matchboxbananasynergy "@matchboxbananasynergy")
|
||||
- [:simple-mastodon: Mastodon](https://mstdn.social/@matchboxbananasynergy "@matchboxbananasynergy@mstdn.social"){rel=me}
|
||||
- [:fontawesome-solid-envelope: Email](mailto:matchboxbananasynergy@privacyguides.org)
|
||||
- [:fontawesome-solid-house: Homepage](https://banana.omg.lol)
|
||||
|
||||
??? person "@kai"
|
||||
|
||||
- [:simple-discourse: Discourse](https://discuss.privacyguides.org/u/Kai)
|
||||
- [:simple-github: GitHub](https://github.com/KaiTebay "@KaiTebay")
|
||||
- [:fontawesome-solid-house: Homepage](https://kaitebay.com)
|
||||
|
||||
Additionally, [many people](https://github.com/privacyguides/privacyguides.org/graphs/contributors) have made contributions to the project. You can too, we're open sourced on GitHub!
|
||||
|
||||
Our team members review all changes made to the website and handle administrative duties such as web hosting and financials, however they do not personally profit from any contributions made to this site. Our financials are transparently hosted by the Open Collective Foundation 501(c)(3) at [opencollective.com/privacyguides](https://opencollective.com/privacyguides). Donations to Privacy Guides are generally tax deductible in the United States.
|
||||
|
||||
## Site License
|
||||
|
||||
*The following is a human-readable summary of (and not a substitute for) the [license](https://github.com/privacyguides/privacyguides.org/blob/main/LICENSE):*
|
||||
|
||||
:fontawesome-brands-creative-commons: :fontawesome-brands-creative-commons-by: :fontawesome-brands-creative-commons-nd: Unless otherwise noted, the original content on this website is made available under the [Creative Commons Attribution-NoDerivatives 4.0 International Public License](https://github.com/privacyguides/privacyguides.org/blob/main/LICENSE). This means that you are free to copy and redistribute the material in any medium or format for any purpose, even commercially; as long as you give appropriate credit to `Privacy Guides (www.privacyguides.org)` and provide a link to the license. You may do so in any reasonable manner, but not in any way that suggests Privacy Guides endorses you or your use. If you remix, transform, or build upon the content of this website, you may not distribute the modified material.
|
||||
|
||||
This license is in place to prevent people from sharing our work without giving proper credit, and to prevent people from modifying our work in a way that could be used to mislead people. If you find the terms of this license too restrictive for the project you're working on, please reach out to us at `jonah@privacyguides.org`. We are happy to provide alternative licensing options for well-intentioned projects in the privacy space!
|
||||
@ -43,7 +43,7 @@ We will store your account data as long as your account remains open. After clos
|
||||
|
||||
The Privacy Guides team generally does not have access to personal data outside of limited access granted via some moderation panels. Inquiries regarding your personal information should be sent directly to:
|
||||
|
||||
```
|
||||
```text
|
||||
Jonah Aragon
|
||||
Services Administrator
|
||||
jonah@privacyguides.org
|
||||
@ -55,6 +55,6 @@ For complaints under GDPR more generally, you may lodge complaints with your loc
|
||||
|
||||
## About This Policy
|
||||
|
||||
We will post any new versions of this statement [here](privacy-policy.en.md). We may change how we announce changes in future versions of this document. In the meantime we may update our contact information at any time without announcing a change. Please refer to the [Privacy Policy](privacy-policy.en.md) for the latest contact information at any time.
|
||||
We will post any new versions of this statement [here](privacy-policy.md). We may change how we announce changes in future versions of this document. In the meantime we may update our contact information at any time without announcing a change. Please refer to the [Privacy Policy](privacy-policy.md) for the latest contact information at any time.
|
||||
|
||||
A full revision [history](https://github.com/privacyguides/privacyguides.org/commits/main/docs/about/privacy-policy.en.md) of this page can be found on GitHub.
|
||||
A full revision [history](https://github.com/privacyguides/privacyguides.org/commits/main/docs/about/privacy-policy.md) of this page can be found on GitHub.
|
||||
31
docs/about/services.md
Normal file
31
docs/about/services.md
Normal file
@ -0,0 +1,31 @@
|
||||
# Privacy Guides Services
|
||||
|
||||
We run a number of web services to test out features and promote cool decentralized, federated, and/or open-source projects. Many of these services are available to the public and are detailed below.
|
||||
|
||||
[:material-comment-alert: Report an issue](https://discuss.privacyguides.net/c/services/2){ .md-button .md-button--primary }
|
||||
|
||||
## Discourse
|
||||
|
||||
- Domain: [discuss.privacyguides.net](https://discuss.privacyguides.net)
|
||||
- Availability: Public
|
||||
- Source: [github.com/discourse/discourse](https://github.com/discourse/discourse)
|
||||
|
||||
## Gitea
|
||||
|
||||
- Domain: [code.privacyguides.dev](https://code.privacyguides.dev)
|
||||
- Availability: Invite-Only
|
||||
Access may be granted upon request to any team working on *Privacy Guides*-related development or content.
|
||||
- Source: [snapcraft.io/gitea](https://snapcraft.io/gitea)
|
||||
|
||||
## Matrix
|
||||
|
||||
- Domain: [matrix.privacyguides.org](https://matrix.privacyguides.org)
|
||||
- Availability: Invite-Only
|
||||
Access may be granted upon request to Privacy Guides team members, Matrix moderators, third-party Matrix community administrators, Matrix bot operators, and other individuals in need of a reliable Matrix presence.
|
||||
- Source: [github.com/spantaleev/matrix-docker-ansible-deploy](https://github.com/spantaleev/matrix-docker-ansible-deploy)
|
||||
|
||||
## SearXNG
|
||||
|
||||
- Domain: [search.privacyguides.net](https://search.privacyguides.net)
|
||||
- Availability: Public
|
||||
- Source: [github.com/searxng/searxng-docker](https://github.com/searxng/searxng-docker)
|
||||
@ -229,6 +229,25 @@ details[class="downloads annotate"] > p .md-annotation span span::before {
|
||||
list-style-type: none;
|
||||
}
|
||||
|
||||
|
||||
.md-typeset .admonition.person,
|
||||
.md-typeset details.person {
|
||||
border-color: var(--md-default-bg-color);
|
||||
box-shadow: none;
|
||||
background-color: var(--md-default-bg-color);
|
||||
margin: 0;
|
||||
}
|
||||
.md-typeset .person > .admonition-title,
|
||||
.md-typeset .person > summary {
|
||||
background-color: var(--md-default-bg-color);
|
||||
}
|
||||
.md-typeset .person > .admonition-title::before,
|
||||
.md-typeset .person > summary::before {
|
||||
background-color: var(--md-accent-fg-color);
|
||||
-webkit-mask-image: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" height="48" width="48"><path d="M24 23.95q-3.3 0-5.4-2.1-2.1-2.1-2.1-5.4 0-3.3 2.1-5.4 2.1-2.1 5.4-2.1 3.3 0 5.4 2.1 2.1 2.1 2.1 5.4 0 3.3-2.1 5.4-2.1 2.1-5.4 2.1ZM8 40v-4.7q0-1.9.95-3.25T11.4 30q3.35-1.5 6.425-2.25Q20.9 27 24 27q3.1 0 6.15.775 3.05.775 6.4 2.225 1.55.7 2.5 2.05.95 1.35.95 3.25V40Z"/></svg>');
|
||||
mask-image: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" height="48" width="48"><path d="M24 23.95q-3.3 0-5.4-2.1-2.1-2.1-2.1-5.4 0-3.3 2.1-5.4 2.1-2.1 5.4-2.1 3.3 0 5.4 2.1 2.1 2.1 2.1 5.4 0 3.3-2.1 5.4-2.1 2.1-5.4 2.1ZM8 40v-4.7q0-1.9.95-3.25T11.4 30q3.35-1.5 6.425-2.25Q20.9 27 24 27q3.1 0 6.15.775 3.05.775 6.4 2.225 1.55.7 2.5 2.05.95 1.35.95 3.25V40Z"/></svg>');
|
||||
}
|
||||
|
||||
@media screen and (max-width: 600px) {
|
||||
.downloads > ul {
|
||||
grid-template-columns: repeat(2, 1fr);
|
||||
|
||||
@ -1,8 +0,0 @@
|
||||
---
|
||||
title: Code of Conduct
|
||||
hide:
|
||||
- toc
|
||||
- feedback
|
||||
---
|
||||
|
||||
{% include 'CODE_OF_CONDUCT.md' %}
|
||||
@ -43,7 +43,7 @@ It's important for a website like Privacy Guides to always stay up-to-date. We n
|
||||
- [:simple-mastodon: Follow us on Mastodon](https://mastodon.social/@privacyguides){ rel=me }
|
||||
- [:material-book-edit: Contribute to this website](https://github.com/privacyguides/privacyguides.org)
|
||||
- [:simple-matrix: Chat with us on Matrix](https://matrix.to/#/#privacyguides:matrix.org)
|
||||
- [:material-information-outline: Learn more about us](about.md)
|
||||
- [:material-information-outline: Learn more about us](about/index.md)
|
||||
- [:material-hand-coin-outline: Support the project](about/donate.md)
|
||||
|
||||
</div>
|
||||
|
||||
22
docs/meta/brand.md
Normal file
22
docs/meta/brand.md
Normal file
@ -0,0 +1,22 @@
|
||||
---
|
||||
title: Branding Guidelines
|
||||
---
|
||||
|
||||
The name of the website is **Privacy Guides** and should **not** be changed to:
|
||||
|
||||
<div class="pg-red" markdown>
|
||||
- PrivacyGuides
|
||||
- Privacy guides
|
||||
- PG
|
||||
- PG.org
|
||||
</div>
|
||||
|
||||
The name of the subreddit is **r/PrivacyGuides** or **the Privacy Guides Subreddit**.
|
||||
|
||||
Additional branding guidelines can be found at [github.com/privacyguides/brand](https://github.com/privacyguides/brand)
|
||||
|
||||
## Trademark
|
||||
|
||||
"Privacy Guides" and the shield logo are trademarks owned by Jonah Aragon, unlimited usage is granted to the Privacy Guides project.
|
||||
|
||||
Without waiving any of its rights, Privacy Guides does not advise others on the scope of its intellectual property rights. Privacy Guides does not permit or consent to any use of its trademarks in any manner that is likely to cause confusion by implying association with or sponsorship by Privacy Guides. If you are aware of any such use, please contact Jonah Aragon at jonah@privacyguides.org. Consult your legal counsel if you have questions.
|
||||
45
docs/meta/git-recommendations.md
Normal file
45
docs/meta/git-recommendations.md
Normal file
@ -0,0 +1,45 @@
|
||||
---
|
||||
title: Git Recommendations
|
||||
---
|
||||
If you make changes to this website on GitHub.com's web editor directly, you shouldn't have to worry about this. If you are developing locally and/or are a long-term website editor (who should probably be developing locally!), consider these recommendations.
|
||||
|
||||
## Enable SSH Key Commit Signing
|
||||
|
||||
You can use an existing SSH key for signing, or [create a new one](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent).
|
||||
|
||||
1. Configure your Git client to sign commits and tags by default (remove `--global` to only sign by default for this repo):
|
||||
```
|
||||
git config --global commit.gpgsign true
|
||||
git config --global gpg.format ssh
|
||||
git config --global tag.gpgSign true
|
||||
```
|
||||
2. Copy your SSH public key to your clipboard, for example:
|
||||
```
|
||||
pbcopy < ~/.ssh/id_ed25519.pub
|
||||
# Copies the contents of the id_ed25519.pub file to your clipboard
|
||||
```
|
||||
3. Set your SSH key for signing in Git with the following command, replacing the last string in quotes with the public key in your clipboard:
|
||||
```
|
||||
git config --global user.signingkey 'ssh-ed25519 AAAAC3(...) user@example.com'
|
||||
```
|
||||
|
||||
Ensure you [add your SSH key to your GitHub account](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account#adding-a-new-ssh-key-to-your-account) **as a Signing Key** (as opposed to or in addition to as an Authentication Key).
|
||||
|
||||
## Rebase on Git pull
|
||||
|
||||
Use `git pull --rebase` instead of `git pull` when pulling in changes from GitHub to your local machine. This way your local changes will always be "on top of" the latest changes on GitHub, and you avoid merge commits (which are disallowed in this repo).
|
||||
|
||||
You can set this to be the default behavior:
|
||||
|
||||
```
|
||||
git config --global pull.rebase true
|
||||
```
|
||||
|
||||
## Rebase from `main` before submitting a PR
|
||||
|
||||
If you are working on your own branch, run these commands before submitting a PR:
|
||||
|
||||
```
|
||||
git fetch origin
|
||||
git rebase origin/main
|
||||
```
|
||||
89
docs/meta/uploading-images.md
Normal file
89
docs/meta/uploading-images.md
Normal file
@ -0,0 +1,89 @@
|
||||
---
|
||||
title: Uploading Images
|
||||
---
|
||||
|
||||
Here are a couple of general rules for contributing to Privacy Guides:
|
||||
|
||||
## Images
|
||||
|
||||
- We **prefer** SVG images, but if those do not exist we can use PNG images
|
||||
|
||||
Company logos have canvas size of:
|
||||
|
||||
- 128x128px
|
||||
- 384x128px
|
||||
|
||||
## Optimization
|
||||
|
||||
### PNG
|
||||
|
||||
Use the [OptiPNG](https://sourceforge.net/projects/optipng/) to optimize the PNG image:
|
||||
|
||||
```bash
|
||||
optipng -o7 file.png
|
||||
```
|
||||
|
||||
### SVG
|
||||
|
||||
#### Inkscape
|
||||
|
||||
[Scour](https://github.com/scour-project/scour) all SVG images.
|
||||
|
||||
In Inkscape:
|
||||
|
||||
1. File Save As..
|
||||
2. Set type to Optimized SVG (*.svg)
|
||||
|
||||
In the **Options** tab:
|
||||
|
||||
- **Number of significant digits for coordinates** > **5**
|
||||
- [x] Turn on **Shorten color values**
|
||||
- [x] Turn on **Convert CSS attributes to XML attributes**
|
||||
- [x] Turn on **Collapse groups**
|
||||
- [x] Turn on **Create groups for similar attributes**
|
||||
- [ ] Turn off **Keep editor data**
|
||||
- [ ] Turn off **Keep unreferenced definitions**
|
||||
- [x] Turn on **Work around renderer bugs**
|
||||
|
||||
In the **SVG Output** tab under **Document options**:
|
||||
|
||||
- [ ] Turn off **Remove the XML declaration**
|
||||
- [x] Turn on **Remove metadata**
|
||||
- [x] Turn on **Remove comments**
|
||||
- [x] Turn on **Embeded raster images**
|
||||
- [x] Turn on **Enable viewboxing**
|
||||
|
||||
In the **SVG Output** under **Pretty-printing**:
|
||||
|
||||
- [ ] Turn off **Format output with line-breaks and indentation**
|
||||
- **Indentation characters** > Select **Space**
|
||||
- **Depth of indentation** > **1**
|
||||
- [ ] Turn off **Strip the "xml:space" attribute from the root SVG element**
|
||||
|
||||
In the **IDs** tab:
|
||||
|
||||
- [x] Turn on **Remove unused IDs**
|
||||
- [ ] Turn off **Shorten IDs**
|
||||
- **Prefix shortened IDs with** > `leave blank`
|
||||
- [x] Turn on **Preserve manually created IDs not ending with digits**
|
||||
- **Preserve the following IDs** > `leave blank`
|
||||
- **Preserve IDs starting with** > `leave blank`
|
||||
|
||||
#### CLI
|
||||
|
||||
The same can be achieved with the [Scour](https://github.com/scour-project/scour) command:
|
||||
|
||||
```bash
|
||||
scour --set-precision=5 \
|
||||
--create-groups \
|
||||
--renderer-workaround \
|
||||
--remove-descriptive-elements \
|
||||
--enable-comment-stripping \
|
||||
--enable-viewboxing \
|
||||
--indent=space \
|
||||
--nindent=1 \
|
||||
--no-line-breaks \
|
||||
--enable-id-stripping \
|
||||
--protect-ids-noninkscape \
|
||||
input.svg output.svg
|
||||
```
|
||||
87
docs/meta/writing-style.md
Normal file
87
docs/meta/writing-style.md
Normal file
@ -0,0 +1,87 @@
|
||||
---
|
||||
title: Writing Style
|
||||
---
|
||||
|
||||
Privacy Guides is written in American English, and you should refer to [APA Style guidelines](https://apastyle.apa.org/style-grammar-guidelines/grammar) when in doubt.
|
||||
|
||||
In general the [United States federal plain language guidelines](https://www.plainlanguage.gov/guidelines/) provide a good overview of how to write clearly and concisely. We highlight a few important notes from these guidelines below.
|
||||
|
||||
## Writing for our audience
|
||||
|
||||
Privacy Guides' intended [audience](https://www.plainlanguage.gov/guidelines/audience/) is primarily average, technology using adults. Don't dumb down content as if you are addressing a middle-school class, but don't overuse complicated terminology about concepts average computer users wouldn't be familiar with.
|
||||
|
||||
### Address only what people want to know
|
||||
|
||||
People don't need overly complex articles with little relevance to them. Figure out what you want people to accomplish when writing an article, and only include those details.
|
||||
|
||||
> Tell your audience why the material is important to them. Say, “If you want a research grant, here’s what you have to do.” Or, “If you want to mine federal coal, here’s what you should know.” Or, “If you’re planning a trip to Rwanda, read this first.”
|
||||
|
||||
### Address people directly
|
||||
|
||||
We're writing *for* a wide variety of people, but we are writing *to* the person who is actually reading it. Use "you" to address the reader directly.
|
||||
|
||||
> More than any other single technique, using “you” pulls users into the information and makes it relevant to them.
|
||||
>
|
||||
> When you use “you” to address users, they are more likely to understand what their responsibility is.
|
||||
|
||||
Source: [plainlanguage.gov](https://www.plainlanguage.gov/guidelines/audience/address-the-user/)
|
||||
|
||||
### Avoid "users"
|
||||
|
||||
Avoid calling people "users", in favor of "people", or a more specific description of the group of people you are writing for.
|
||||
|
||||
## Organizing content
|
||||
|
||||
Organization is key. Content should flow from most to least important information, and use headers as much as needed to logically separate different ideas.
|
||||
|
||||
- Limit the document to around five or six sections. Long documents should probably be broken up into separate pages.
|
||||
- Mark important ideas with **bold** or *italics*.
|
||||
|
||||
Source: [plainlanguage.gov](https://www.plainlanguage.gov/guidelines/design/)
|
||||
|
||||
### Begin with a topic sentence
|
||||
|
||||
> If you tell your reader what they’re going to read about, they’re less likely to have to read your paragraph again. Headings help, but they’re not enough. Establish a context for your audience before you provide them with the details.
|
||||
>
|
||||
> We often write the way we think, putting our premises first and then our conclusion. It may be the natural way to develop thoughts, but we wind up with the topic sentence at the end of the paragraph. Move it up front and let users know where you’re going. Don’t make readers hold a lot of information in their heads before getting to the point.
|
||||
|
||||
Source: [plainlanguage.gov](https://www.plainlanguage.gov/guidelines/organize/have-a-topic-sentence/)
|
||||
|
||||
## Choose your words carefully
|
||||
|
||||
> Words matter. They are the most basic building blocks of written and spoken communication. Don’t complicate things by using jargon, technical terms, or abbreviations that people won’t understand.
|
||||
|
||||
We should try to avoid abbreviations where possible, but technology is full of abbreviations. In general, spell out the abbreviation/acronym the first time it is used on a page, and add the abbreviation to the abbreviation glossary file when it is used repeatedly.
|
||||
|
||||
> Kathy McGinty offers tongue-in-cheek instructions for bulking up your simple, direct sentences:
|
||||
>
|
||||
> > There is no escaping the fact that it is considered very important to note that a number of various available applicable studies ipso facto have generally identified the fact that additional appropriate nocturnal employment could usually keep juvenile adolescents off thoroughfares during the night hours, including but not limited to the time prior to midnight on weeknights and/or 2 a.m. on weekends.
|
||||
>
|
||||
>And the original, using stronger, simpler words:
|
||||
>
|
||||
> > More night jobs would keep youths off the streets.
|
||||
|
||||
## Be concise
|
||||
|
||||
> Unnecessary words waste your audience’s time. Great writing is like a conversation. Omit information that the audience doesn’t need to know. This can be difficult as a subject matter expert so it’s important to have someone look at the information from the audience’s perspective.
|
||||
|
||||
Source: [plainlanguage.gov](https://www.plainlanguage.gov/guidelines/concise/)
|
||||
|
||||
## Keep text conversational
|
||||
|
||||
> Verbs are the fuel of writing. They give your sentences power and direction. They enliven your writing and make it more interesting.
|
||||
>
|
||||
> Verbs tell your audience what to do. Make sure it’s clear who does what.
|
||||
|
||||
### Use active voice
|
||||
|
||||
> Active voice makes it clear who is supposed to do what. It eliminates ambiguity about responsibilities. Not “It must be done,” but “You must do it.”
|
||||
|
||||
Source: [plainlanguage.gov](https://www.plainlanguage.gov/guidelines/conversational/use-active-voice/)
|
||||
|
||||
### Use "must" for requirements
|
||||
|
||||
> - “must” for an obligation
|
||||
> - “must not” for a prohibition
|
||||
> - “may” for a discretionary action
|
||||
> - “should” for a recommendation
|
||||
@ -7,13 +7,15 @@ plugins:
|
||||
- api.privacyguides.net/*
|
||||
- giscus.app/*
|
||||
git-committers:
|
||||
enabled: !ENV [PRODUCTION, false]
|
||||
repository: privacyguides/privacyguides.org
|
||||
branch: main
|
||||
git-revision-date-localized:
|
||||
exclude:
|
||||
- index.en.md
|
||||
enabled: !ENV [PRODUCTION, false]
|
||||
exclude:
|
||||
- index.en.md
|
||||
social:
|
||||
cards: !ENV [CARDS, false]
|
||||
cards: !ENV [PRODUCTION, false]
|
||||
cards_color:
|
||||
fill: "#FFD06F"
|
||||
text: "#2d2d2d"
|
||||
@ -42,6 +44,7 @@ theme:
|
||||
- navigation.tracking
|
||||
- navigation.tabs
|
||||
- navigation.sections
|
||||
- navigation.expand
|
||||
- content.tooltips
|
||||
- search.highlight
|
||||
palette:
|
||||
|
||||
19
mkdocs.yml
19
mkdocs.yml
@ -169,14 +169,23 @@ nav:
|
||||
- 'real-time-communication.md'
|
||||
- 'video-streaming.md'
|
||||
- 'About':
|
||||
- 'about.md'
|
||||
- 'coc.md'
|
||||
- 'about/donate.md'
|
||||
- 'Online Services': 'https://privacyguides.net'
|
||||
- 'about/privacytools.md'
|
||||
- 'about/index.md'
|
||||
- 'about/criteria.md'
|
||||
- 'about/statistics.md'
|
||||
- 'about/notices.md'
|
||||
- 'about/privacy-policy.md'
|
||||
- 'Community':
|
||||
- 'about/donate.md'
|
||||
- 'Online Services': 'about/services.md'
|
||||
- 'Code of Conduct': 'CODE_OF_CONDUCT.md'
|
||||
- 'about/privacytools.md'
|
||||
- 'Contributing':
|
||||
- 'Writing Guides':
|
||||
- 'meta/writing-style.md'
|
||||
- 'meta/brand.md'
|
||||
- 'Technical Guides':
|
||||
- 'meta/uploading-images.md'
|
||||
- 'meta/git-recommendations.md'
|
||||
- 'Donate': '/about/donate/'
|
||||
- 'Forum': 'https://discuss.privacyguides.org/'
|
||||
- 'Blog': 'https://blog.privacyguides.org/'
|
||||
|
||||
10
netlify.toml
10
netlify.toml
@ -3,7 +3,7 @@
|
||||
command = "mkdocs build --config-file mkdocs.production.yml"
|
||||
|
||||
[context.production.environment]
|
||||
CARDS = "true"
|
||||
PRODUCTION = "true"
|
||||
|
||||
[[redirects]]
|
||||
from = "/.well-known/matrix/*"
|
||||
@ -15,6 +15,14 @@
|
||||
from = "/kb"
|
||||
to = "/basics/threat-modeling/"
|
||||
|
||||
[[redirects]]
|
||||
from = "/coc"
|
||||
to = "/CODE_OF_CONDUCT/"
|
||||
|
||||
[[redirects]]
|
||||
from = "/team"
|
||||
to = "/about/"
|
||||
|
||||
[[redirects]]
|
||||
from = "/browsers"
|
||||
to = "/desktop-browsers/"
|
||||
|
||||
@ -2,11 +2,6 @@
|
||||
{% block extrahead %}
|
||||
<link rel="preload" href="{{ 'assets/brand/WOFF/bagnard/Bagnard.woff' | url }}" as="font" type="font/woff" crossorigin>
|
||||
<link rel="stylesheet" href="{{ 'assets/stylesheets/home.css?v=2.10.0' | url }}">
|
||||
<link rel="me" href="https://aragon.sh/@jonah">
|
||||
<link rel="me" href="https://fosstodon.org/@freddy">
|
||||
<link rel="me" href="https://mastodon.social/@dngray">
|
||||
<link rel="me" href="https://mastodon.social/@blacklight447">
|
||||
<link rel="me" href="https://fosstodon.org/@hook54321">
|
||||
{% endblock %}
|
||||
{% block tabs %}
|
||||
{{ super() }}
|
||||
|
||||
Loading…
Reference in New Issue
Block a user