Commit ba904990 authored by Aral Balkan's avatar Aral Balkan

Updated Blockdown guide in readme. Progress towards #293.

parent 8d6fa946
......@@ -77,92 +77,89 @@ Blockdown is Markdown with an extended high-level vocabulary for describing web
Site pages have the following sections:
### Ethical design violations
```markdown
## Ethical design violations
```
This is a list of ethical design violations that gets converted to a collection of badges on the rendered site pages.
This is a list of ethical design violations that gets converted to a collection of badges on the rendered site pages. The Trackers part of the list, detailed below, is updated automatically by [Better Inspector](https://source.ind.ie/better/inspector)
#### Trackers
The first badge is always the trackers badge. In Blockdown it is represented by a list item introduced by the word `Trackers`:
```markdown
* Trackers (exposes you to NNN third-party sites)
```
We get the statistic for the number of third-party sites that a person browsing the site is exposed to by using [Mozilla Lightbeam](https://www.mozilla.org/en-US/lightbeam/).
Following the badge heading list item, there is a sublist of site URLs. For example, here’s an excerpt from the [cultofmac.com site page](https://better.fyi/sites/cultofmac.com):
```markdown
* Trackers (exposes you to 155 third-party sites)
* w.soundcloud.com
* goroost.com
* taboola.com
* google-syndication.com
*
* Trackers
* Automatically
* Generated
* List
* of
* Trackers
```
This gets automatically translated by [Better Builder](https://source.ind.ie/better/builder) to a badge similar to the one below:
![Screenshot of the trackers badge](images/readme/blockdown/trackers-badge-example.png)
Specifically, the builder counts the number of trackers for you and juxtapositions that with the number of third-party sites that you entered manually.
Tapping on the badge displays a popover with links to the actual trackers.
![Screenshot of the trackers popover](images/readme/blockdown/trackers-popover-example.png)
Trackers is the only section that is required for a site entry. The other badges should be used as and when they apply to a site.
The other badges are manually added if they apply to the site in question:
#### Aggressive
```markdown
* Aggressive: Attempts to block content blockers.
* Aggressive
```
Attempts to block content blockers.
![Screenshot of the Aggressive Badge](images/readme/blockdown/aggressive-badge-example.png)
#### Doorslam
```markdown
* Doorslam: Interrupts and blocks using modal dialogs.
* Doorslam
```
Interrupts and blocks using modal dialogs.
![Screenshot of the Doorslam Badge](images/readme/blockdown/doorslam-badge-example.png)
#### Clickbait
```markdown
* Clickbait: Uses exploitative, addictive content syndication network(s).
* Clickbait
```
Uses exploitative, addictive content syndication network(s).
![Screenshot of the Clickbait Badge](images/readme/blockdown/clickbait-badge-example.png)
#### Fingerprint
```markdown
* Fingerprint: Uses hidden Canvas fingerprinting.
* Fingerprint
```
Uses hidden Canvas fingerprinting.
![Screenshot of the Fingerprint Badge](images/readme/blockdown/fingerprint-badge-example.png)
#### Web Bugs
#### Web Bug
```markdown
* Web bugs: Uses invisible tracking pixels.
* Web bug
```
Uses invisible tracking pixels.
![Screenshot of the Web Bugs Badge](images/readme/blockdown/web-bugs-badge-example.png)
We might create new badges as and when we find new types of web malware and unethical practices to document and warn people about.
......@@ -175,19 +172,7 @@ We might create new badges as and when we find new types of web malware and unet
The After Better section provides statistics about the before (without the Better content blocker active) and after (with the Better content blocker active) performance of a site.
The statistics are gathered using the Safari Web Inspector’s Timelines view.
Here is an example from the [cultofmac.com site page](https://better.fyi/sites/cultofmac.com):
```markdown
* Weight: 11.5MB to 3.22MB
* Speed: 10.38secs to 1.75secs
* Resources: 458 to 63
* Errors: 422 to 2
* Warnings: 19 to 13
```
The statistics in this section are translated into a graph and table view for the app and the site by Better Builder.
It is automatically generated by [Better Inspector](https://source.ind.ie/better/inspector)
![Screenshot of the After Better Section](images/readme/blockdown/after-better.png)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment