splitting Whonix documentation into a short and long edition for better usability

Website
1

At 32c3 I got some feedback, that even very advanced Linux users and developers give up on Whonix even before getting started because they don’t know what it does and/or because it looks so complicated. Too much verbosity / documentation to get started.

I concluded with @troubadour, that the current Whonix ™ Documentation page should be split into two. A short and a long edition. The short edition as minimal as possible. The long edition, with everything.

Perhaps:

Better page names can be suggested.

The current Whonix ™ Documentation page would become the long edition. The short edition would mention and link to the long edition with an explanatory text such as “if you would like to learn more / become more secure / etc. / missing something / see the documentation long edition”. Perhaps the long edition should include everything the short edition includes.

Please suggest what should absolute [not] go into the short edition.

2
  • cant we make vertical order like qubes ?
  • or like ubuntu

https://help.ubuntu.com/stable/ubuntu-help/

every word under every title is a separated link

  • also kali has something near to it

i dunno if we can make it with current mediawiki or we want special design for it.

3

@nurmagoz:

  • cant we make vertical order like qubes ?

Documentation | Qubes OS

Can you imagine how long it will be then? The previous improvement was
to make it not not vertical. To have it look more like JonDonym
documentation.
( https://anonymous-proxy-servers.net/en/help/index.html )

4

yes but i think we have issue in our documentation atm that we should fix before going ahead to new design , one of which i see it not really necessary is this:-

in the documentation under “Connect to the Internet anonymously” why we r making it look longer by exposing the content of the links ? for example chatting ? do u c the empty circles under chatting = this is one of the reasons the documentation looks long. specially when u look at
“Tunnel Support / Chaining Support”

5

also i think if we gonna make them vertically , it is better to put only the bold titles which like for example:-

  • General information

  • Get Whonix

  • Bugs
    .
    .
    .etc

and they are click-able. like when someone click on “General information” hes going to see these

  • Very brief introduction and summary on Whonix Homepage
  • Why do you need anonymity?
  • The World Wide Web and your privacy
  • Surveillance Capabilities
  • Data Collection Techniques
  • Why does Whonix use Tor?
  • Why is Tor slow?
  • …etc
6

and after finishing from this vertical order , we gonna search and find which documentation topics we can combine together instead of separating them.

for example:-

we can put them all under one topic name , or just some of them and so on for the rest = which will give us less links whta same content.

and long topics maybe better than separated links , because that seems what the ppl r having problem with.

7

Good day,

If I’m honest with you, my hypothesis, which you may take for whatever it is worth, is that the real issue isn’t the extensiveness of our documentation (just look at other “more mainstream” projects like Kali or Tails) or that it is hard to understand what Whonix does (it is explained rather “snappy” on the homepage, together with a very telling picture) but rather that the documentation is our “main site”. Let me rephrase that:

When informing about one of the mentioned projects (or, since a rather short time, also Qubes) you get a light, beautiful page, explaining the advantages and disadvantages in a way everyone may understand. Preferably with some nice, rather abstract graphics (a lock for security/encryption, a pair of glasses for surveillance, etc.) which are written in the public consciousness and are thus easily understood. So, when you look at such a project for the first time, you won’t get overwhelmed. And I think this “overwhelming” amount of information is the problem of Whonix. It’s not so much, that the information in the documentation is by such a noticeable degree more complex than in other projects, it is just that we don’t really hide this information, which makes it seem more complex than it is. When I for one, started reading up about Whonix, I felt rather unqualified, due to the amount of documentation I was presented with from the start. Mind you, it wasn’t what was written in there that scared me, but just the amount. After starting to read what I was presented with, I soon noticed that, thanks to the way everything is formulated, it actually is rather easy to follow.

To be honest, I for one, don’t think splitting the documentation will address this problem, as it would only let people think that they may miss out on something and end up reading the extensive documentation anyways, in fear of being less well equipped.

Have a nice day,

Ego

8

@Ego, I agree with that. Also the main page needs to be made a lot more snappy. We have a thread for that already.

https://forums.whonix.org/t/new-qubes-website-new-whonix-website

Anyhow. It’s still worthwhile to improve the documentation page. Ubuntu and Kali do both present it in a more pretty way.

10

I am not in favor of “multiple editions”. This just presents another stressful decision that newcomers are ill-equipped to make. Should I click the button that will make me a semi-ignorant and perhaps vulnerable user? Or should I click the button that will put me in way over my head and make me quit halfway through?

The current documentation should be better categorized and continue to exist as an index page for advanced users. [Labeled Documentation on header]

Drawing from these pages, a Getting Started / Tutorial should be made that branches through individual needs while covering all of the essential topics. [Labeled Getting Started on header]

    Getting Started
    |
    The Privacy Battle
    |
    How Whonix Works
    |
    How Whonix Compares
    |
    Which Whonix (Simple criteria for deciding)
    |                 |                |
    Vbox              KVM              Qubes
    |                 |                |
    Basic: host security, downloads, install steps
    First connection to Tor (incl bridges)
    Using Tor Browser |                |
    |__________________________________|
    |
    What Not to Do
    |
    What Can I Do / Where to go from here
    Links to:
    Office, Email, Software Included with Whonix
    Install your own software
    Full Documentation

That’s it - just one guide. Everything else is an advanced topic (DIY) documented on index page.

In practice, not so easy. @tempest’s guide mostly covers just the essentials and is 400+ pages long - though that’s counting multiple OS installs, usb install and LOTS of screenshots (nice to have). His guide does what the website has not done yet - hold a complete newbie’s hand through the entire process.

3 Likes
11

Good day,

While I very much agree with you (just look at my previous post in here) there needs to be a way to make entrance easier. 400 pages are quite a lot for those who rely on Whonix in journalism, etc.

What I feel is necessary to happen is that we take a very careful look at the current documentation and think about streamlining it. Your concept of different categories could be a part of the solution. Rewriting old text may be another one.

For the time being though, I need to find some way of replacing mediawiki without losing editability and without relying on JS. Am currently looking therfore into Jekyll as it is used by Qubes as well and seems to over the necessary features. Maybe using it for the homepage may be considerable though I need to look into all the scripts necessary to keep it running.

Have a nice day,

Ego

2 Likes
12

Here are some of my notes on jekyll.
https://www.whonix.org/wiki/Dev/jekyll

Btw with jekyll / git / github also http://prose.io as the web editing tool matches quite well. Example:
Prose · A Content Editor for GitHub
(also available for installation on own servers)

13

Good day,

Please regard what I wrote here when it comes to Jekyll as a solution for documentation: Whonix vs Qubes Docs - #8 by Ego

DokuWiki may be worth a look.

Have a nice day,

Ego

14

Tracking this now as ticket with milestone Whonix 14:

simplify Whonix ™ Documentation
⚓ T521 simplify https://www.whonix.org/wiki/Documentation

15

Since no one is disagreeing with what @entr0py suggested in post 10, let’s go with that.

Anyone available to contribute/apply the suggested changes? @entr0py?

1 Like
16

I think the first step should be organizing the existing documentation: categorizing, merging, deprecating, etc.

Some criteria for categories:

  1. Needs to fit exiting pages
  2. Should be general / agnostic / scalable as warranted
  3. These categories are for the master / advanced documentation index. Designed for browsing and/or search and not in any kind of optimal reading order. The eventual Getting Started guide can draw on these topics in a more approachable manner.

Proposed Categories:

  1. About Whonix
  • mission, description, comparison, threat model, history, etc
  1. Host Operating Systems
  • selection, basic! security, links
  1. Virtualization Platforms
  • qubes, kvm, virtualbox
  • installation, hardening
  1. Anonymization Networks
  • tor, i2p, jondo
  • config, best practices
  1. Censorship Circumvention
  2. Tunneling
  • combining anonymization networks
  • chaining proxies
  1. Encryption
  2. Communications
  • email, irc, im, voip
  1. Applications
  • productivity, audio/video, printing/scanning, money
  1. Advanced Whonix Configuration

EDIT: added ‘Censorship Circumvention’

2 Likes
17

Good day,

I may be able to organize the whole thing in this way, however only after the 25 of June.

Have a nice day,

Ego

2 Likes
18

@entr0py @ego

JonDoNym vs Qubes vs TAILS vs Tor - Documentation Chapters Comparison (# = position in documentation)

Introduction, General Information & The Basics (1,1,1,1)
Design Specifications (N/A, N/A, N/A, 2)
Hardware Recommendation(N/A, 2, N/A, N/A)
Installation and Upgrading (2, 3, 2, N/A)
First Steps (N/A, N/A, 3, N/A)
Common Tasks (5 & 10-11, 4, N/A, N/A)
Managing Virtual Operating Systems (N/A, 5, N/A, N/A)
Use of Premium Services (3, N/A, N/A, N/A)
Security Guides (N/A, 6, N/A, N/A)
Preserving Anonymity & Privacy (4 & 6-7, 7, 4, N/A)
Encryption & Privacy (N/A, N/A, 5, N/A)
Work on Sensitive Documents (N/A, N/A, 6, N/A)
JonDo/Tor-Secure-Live-DVD (9, N/A, N/A, N/A)
Circumvent blocking (12, N/A, N/A, N/A)
Configuration Guides & Advanced Topics (13, 8, 7, N/A)
Customization Guides (N/A, 9, N/A, N/A)
Troubleshooting (14, 10, N/A, N/A)
Credits, License (15, N/A, N/A, N/A)
Reference Pages & Neat Links (N/A, 11, N/A, 3)
Developers Guide (N/A, 12, N/A, 4)

As at 5-6th June 2016. See: JonDo Help: TOC, Redirecting…, Tails - Documentation, How can we help? | Tor Project | Support

If you look at most of these docs on-line, they are pretty simple (even Qubes!) So, if Whonix adopted a similar structure for a simplified guide, I think it should cover off the following (relevant) entries in roughly this order:

Suggested Simplified (Short Version) Table of Contents - Whonix

  1. An Introduction to Whonix
  2. Whonix Design and Hardware Requirements
  3. Installation and Updating (Upgrading)
  4. First Steps in Whonix
  5. Common Tasks
  6. Managing / Fine-tuning Virtualization Platforms
  7. Security Guide
  8. Preserving Anonymity and Privacy
  9. Configuration / Customization Guides*
  10. Troubleshooting
  11. Credits, License
  12. Reference Pages**

*Simple (common) configuration changes only
**Reference pages is where a lot of terminal commands and output can be hidden, just like in the Qubes documentation. This saves pages of intimidating terminal output being shoved in the new user’s face and provides a handy link for the most commonly used commands.

Now, compare this to Entropy’s proposed guide above for the ‘Advanced (Long) Manual’.

Main Point: The simple menu structure I have proposed is very similar, except it drops off all advanced topics/configuration, chaining/tunneling experiments, censorship circumvention, work on sensitive documents, developer/bug stuff and general encryption discussions. Plus it is based on a winning documentation formula from four other privacy/anonymity websites.

Slashing the size of the material is essential for the simplified (short) version. Around half (?) of the full Whonix index appears to be advanced/esoteric/misc. topics. General discussions around safely using email and other common programs would of course be covered off in the security chapter and draw on relevant material where required.

If I were to assist with creating a short, beginner-friendly version that won’t scare away Patrick’s engineer friends, then I would be unapologetic in heavily editing the content e.g. tone, readability, and harshly slashing it in size. 20-40 footnotes per page and an academic/research tone can remain in the advanced document. :smile:

End goal: the guide allows a basic computer user (non-Linux-guru) to easily install a safe (verified) version of Whonix in a suitable virtualization platform, update/upgrade, troubleshoot & fine-tune simple issues as required, and have a working Tor browser and other basic programs within short order.

Outcome: A steady increase in the size of the Whonix user base as it is introduced to a much larger audience - evidenced in stats at Linux distrowatch and elsewhere (which I note are creeping up!).

If this is combined with a visually friendly ‘button’ approach as discussed on the other thread instead of huge blocks of text, then Whonix won’t be so scary anymore to the masses. Or if large chunks of text must still remain, they should be broken up periodically with tables, snapshots etc to reduce the visual monotony.

I’m not sure how long it would take - depends on time, expectations of developers etc. If I am to assist, I wonder how a draft document is best created? I could easily do it in LibreOffice, but I suspect you want it all done in html or something that I’m not readily familiar with i.e. so it is web-ready.

1 Like
19

What you’re proposing almost sounds like a 3rd version of the documentation: “Comprehensive Guide for Beginners”

The Getting Started guide that I had envisioned would be much simpler and would serve to get new users up & running in 30-60 mins (depending on virt platform). I think your “End goal” captures all the requirements:

To that end, I would cut #6,7,9,11,12. Instead provide links to the main docs. Whonix has safe defaults so little / no configuration should be required.

Building on your outline:

1. An Introduction to Whonix
  a. What is Whonix
  b. How is Whonix different from other Anonymity Distributions
2. Installation and Updating (Upgrading)
  a. Choose a Virtualization Platform
    * Hardware Requirements
    * Host Recommendations
  b. Download, verify
  c. Install
3. First Steps in Whonix
  a. Launch, connect
    * censored? click link to main docs
  b. Update
  c. Browse the Web
  d. Shutdown
4. Common Tasks
  a. Pre-Installed Applications
  b. Need something else? click link
5. Preserving Anonymity and Privacy
  a. What to do & What not to do
6. Where to go from here (links)
  a. multiple browsers/gateways/workstations
  b. tunnels
  c. other applications
  d. hardened configurations
3 Likes
20

Good day,

Have to say that I very much like all the input you (the same goes for @torjunkie) are putting up. However, first I feel like we need to establish a system which allows the implementation of one of the proposed “guides”. Looking at all the test I’m currently making (both with Media- and Dokuwiki, as well as some custom solutions), I have to say though that to a certain degree, the choice of documentation software will have quite an impact on how the “short documentation” will end up looking.

An idea I thus had, and you may tell me if this sounds like it would create to much overhead, was keeping all the current documentation in its current state. The “short” one however, would be seperate from the rest, not in an own wiki, but rather on Jekyll based sites made to look simpler and more welcoming. Something like this for the “short introduction”: Configuration | Jekyll • Simple, blog-aware, static sites The rest of the documentation thus would still be in a “normal” wiki, whatever we choose in the end.

The advantages of this?

*) Looks more friendly to newcomers than a full-blown wiki.

*) Easy to seperate from the extended documentation.

The disadvantages?

*) Everything needs to be edited on two seperate places.

A bit input on this proposal would be nice.

Have a nice day,

Ego

3 Likes