Tails

#2 Updated by ArgySan 2015-05-24 18:58:56

• Assignee set to ArgySan

If it’s OK, I’d like to pump out some documentation for this, utilizing the MAT (https://mat.boum.org/) page, and other, maybe more ‘general’ wording for non-techies.

#5 Updated by sajolida 2015-05-26 13:11:49

• Description updated

#6 Updated by sajolida 2015-06-10 14:45:22

• QA Check set to Dev Needed

Hi, thanks a lot for working on this.

I don’t think it’s too simplistic and rather think that it should be further simplified :) You’re providing the right information and it is well structured but here are a bunch of recommendations that will make you text even better:

• I would restructure the page to remove the first two titles and merge their content as an intro in a single block without title, like we do on /doc/advanced_topics/paperkey/.
• Explain metadata in simple words, cf. /doc/sensitive_documents/metadata/ and /doc/about/warning/. If you manage to only insert and not modify parts of /doc/sensitive_documents/metadata/, then I can maybe create an inline to include the same text in both places.
• Maybe some examples here would explain the best what are metadata. Maybe you can reuse stuff that’s already on the MAT homepage: https://mat.boum.org/.
• I’m not sure about the need of the title for the section “Why do we care?”. Maybe reusing stuff from those warnings might be enough. But we can see later.
• I like the list of supported formats. Maybe we could make it a bit more compact by having only one line for each of image formats, documents, audio formats.
• Maybe we can further simplify this list by listing only the corresponding file name extensions when they really bring something. For example, I’m not sure it’s needed to specify for JPEG, Ogg Vorbis, Torrent, and maybe others. Now I see that you copied this list from MAT (which was a good idea). But maybe our objectives here are a bit different. In Tails we want to make our users understand as quickly as possible if MAT will work on their files, while in MAT they have to provide a complete and technically unambiguous list for reference.
• Can you find a title for the page looking at the style we usually use for other tools? That would go in the [[!meta title=""]] directive.
• Check how we write the markup for menu paths in /contribute/how/documentation/guidelines/.
• Add a link to upstream (https://mat.boum.org/).
• We try to write our doc as consise as possible. It’s ok to have as very few words on a page as long as they provide the information we need. People will get it faster and translators will have less work to do. In the light on this, I suggest you edit your text again once or two and look for words or parts of sentences that can be removed without loosing meaning. You can probably lower your total word count by 30% or 50% while still improving the quality of the text. For example, I could spot " and our ‘privacy for anyone, anywhere’ mantra“, ”So, to ensure you stay anonymous“, ” in the Tails GUI".
• Try to stay neutral regarding what people might or might not find “easy” or “simple”. For example I would replace or get rid of “Simply put”.
• Avoid jargon, use only words that people are likely to know already or that you want them to learn by providing an explanation. I’m not sure of “watermarks”, “steganographic”, “embedded” are likely to be understood. Remember than many (if not most) of our readers are not native English speakers.
• Avoid the future tense (“will”) which most of the time introduces unecessary ambiguity about when the action will happen. For example “the original author will likely be aware” → “the original author is likely aware”, “MAT will protect you” → “MAT protects you”.
• Limit your sentence to 20-25 words in general. Even if providing the same content, breaking it into several sentences make it easier to read and understand.
• “Toolkit” → “tool”
• “Utilize” → “use”, see https://en.wikipedia.org/wiki/Politics_and_the_English_Language “Never use a long word where a short one will do.”
• Avoid abbreviations like “GUI” (maybe “graphical” or nothing will do) and “CLI” (see what we do on /doc/advanced_topics/paperkey/).
• If you want to go deeper into these consideration, the GNOME Documentation Style Guide is a very good start. See https://developer.gnome.org/gdp-style-guide/.

Good luck with all that :)

Once you’re done you can assign the ticket to me and mark it’s “QA Check” as “Ready for QA”.

#7 Updated by sajolida 2015-06-10 14:48:50

• Blueprint set to https://tails.boum.org/blueprint/mat/

Oh, and I forgot. I create you a blueprint on which you can work from the website: https://tails.boum.org/blueprint/doc/mat/. Click on the wrench icon and then Edit.

#9 Updated by BitingBird 2016-10-16 05:53:51

• Assignee deleted (ArgySan)
• QA Check deleted (Dev Needed)

No answer in a year -> unassigning

#11 Updated by Anonymous 2018-01-17 16:56:29

• Starter set to Yes

#12 Updated by sajolida 2018-03-12 16:06:20

• blocks Feature #14758: Core work 2017Q4 → 2018Q1: Technical writing added

#13 Updated by sajolida 2018-03-12 16:06:35

• related to Bug #15398: Document pdf-redact-tools added

#14 Updated by sajolida 2018-03-14 10:03:48

• blocks Feature #15411: Core work 2018Q2 → 2018Q3: Technical writing added

#15 Updated by sajolida 2018-03-14 10:04:06

• blocked by deleted (Feature #14758: Core work 2017Q4 → 2018Q1: Technical writing)

#16 Updated by sajolida 2018-04-11 13:20:47

• Assignee set to cbrownstein

Assigning to Cody as proposed when we met last week.

#17 Updated by sajolida 2018-07-19 08:33:03

• Assignee deleted (cbrownstein)

#18 Updated by sajolida 2018-09-10 14:11:07

• blocked by deleted (Feature #15411: Core work 2018Q2 → 2018Q3: Technical writing)

#19 Updated by sajolida 2020-01-07 08:51:58

• Subject changed from Document MAT to Document metadata analysis tools
• Description updated

#20 Updated by sajolida 2020-02-11 14:05:26

• Subject changed from Document metadata analysis tools to Document MAT and metadata