wiki/src/contribute/how/documentation.mdwn

   1 [[!meta title="Improve Tails documentation"]]
   2
   3 <div id="intro">
   4
   5 <p>Tails documentation would greatly benefit from your help.</p>
   6
   7 [[!toc levels=2]]
   8
   9 </div>
  10
  11 Good documentation is difficult to keep up-to-date. If you find a typo
  12 or an error in the documentation please let us know — ideally, by
  13 submitting a patch with your correction.
  14
  15 # Find a task
  16
  17 The documentation on the website is not freely editable. The way we
  18 document things has serious security implications. People should be able
  19 to trust the Tails website as much as they trust Tails itself.
  20 Furthermore, every change in the documentation possibly breaks the
  21 translations that were made of the previous version.
  22
  23 But there are still many ways you can start contributing:
  24
  25   - We maintain a list of [documentation
  26     tasks](https://redmine.tails.boum.org/code/projects/tails/issues?query_id=172).
  27     You can start writing a draft in the corresponding ticket and then
  28     [[ask us for review|contribute/merge_policy]].
  29
  30   - Small fixes and enhancements to the current documentation are
  31     greatly welcome. This can be done by sending Git patches to
  32     [[tails-dev@boum.org|about/contact#tails-dev]] or by publishing a
  33     [[Git]] branch (for example to a fork on
  34     [GitLab](https://gitlab.com/Tails/tails)). In general,
  35     documentation changes should be based on the `master` branch.
  36
  37 We recommend you to [[build an offline version of the
  38 documentation|contribute/build/website]] to test your contributions
  39 before sharing them with us.
  40
  41 # Guidelines and style
  42
  43 - [[Documentation guidelines|guidelines]]
  44 - [[Documentation style guide|style_guide]]
  45 - [[Checklist for writing release notes|release_notes]]
  46
  47 # Tools
  48
  49 ## Find documentation pages impacted by changes in Tails
  50
  51 The `bin/doc-impacted-by` tool takes two "states" (see its `--help`)
  52 of Tails, and checks the changes between these states against a
  53 database of relationship between documentation pages and the source
  54 files and packages impacting them.
  55
  56 The relationships between documentation and source files are stored in
  57 `doc-source-relationships.yml` in the Git root. It's YAML, and the
  58 format is something like this:
  59
  60 - The `pages` field is mandatory (after all, we want to find the
  61   documentation *pages* that might need to be updated). The remaining
  62   fields list source files and packages impacting these pages.
  63
  64 - All fields are interchangeable between the single and plural forms
  65   (e.g. `page` is the same as `pages`). Similarly, the values can be
  66   either strings, or a lists of strings.
  67
  68 - All string values can use globs and pathspec magic features like
  69   `{foo,bar}`.
  70
  71 To use these tools, please first install the dependencies:
  72
  73     apt install ruby ruby-deep-merge ruby-git ruby-test-unit
  74
  75 <a id="compress-image"></a>
  76
  77 ## Image compression
  78
  79   - Images on our website are compressed and cleaned using the
  80     [[compress-image.sh]] script. To run this script you need the
  81     `optipng`, `advancecomp`, and `mat` packages.
  82
  83 ## QR codes
  84
  85   - To encode and decode QR codes, you can use the [[qrcode-encode.sh]]
  86     and [[qrcode-decode.sh]] scripts. To run these scripts
  87     you need to install the `qrencode` and `zbar-tools` packages.
  88
  89     For example (run from Tails' source root):
  90
  91         wiki/src/contribute/how/documentation/qrcode-encode.sh https://tails.boum.org/
  92
  93     Creates a QR code in tails_boum_org.png. And:
  94
  95         wiki/src/contribute/how/documentation/qrcode-decode.sh tails_boum_org.png
  96
  97     Outputs:
  98
  99         QR-Code:https://tails.boum.org/
 100
 101 # Related pages
 102
 103   - [[Configuration of the production website|contribute/how/website/production]]
 104   - [[Translating Tails|contribute/how/translate]]
 105
 106 # Talk to us
 107
 108 You can subscribe to [[tails-dev@boum.org|about/contact#tails-dev]],
 109 our development mailing list.