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

Website
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
21

Yes, this is what I had in mind as well.

22

Hi ego and entr0py

I like both your ideas - a simpler table of contents and a more presentable web format. :+1:

As editing (rather than web formatting) is the major obstacle time-wise on any documentation, and we seem to have a general ToC consensus, I can get started on editing the material into shape. Any small additions or deletions later on are trivial.

I presume that required Jekyl tags can be easily applied later on for each chapter’s text?

I’d be likely to run Chapter 1 past you after edit v0.1 to check we are all on the same page. It would make sense to have other knowledgeable eyes look over material as it is developed.

It’s probably also worth having a ‘documentation edits’ thread at some point. At any rate, I hope this is achievable within a relatively short period - famous last words :relaxed:

Will check in later after making some progress.

Cheers

23

Let’s keep this as minimal as possible as anything more than essential will overwhelm users. Let’s think of this as a quick start. Or perhaps alternatively to the streamlined documentation there should be a separate quick start page?

Probably negligible.

Probably negligible.

Too advanced.

Which wiki page would that be?

Too advanced. Leave it out please.

Not sure that is important enough.

Not sure that is too much.

Rather click to Bridges wiki page.

24

Yes, I think we’re all on the same page in terms of simplicity, quick start. The categories that you quoted were for the comprehensive, “everything” docs.

1 Like
25

OK - will look at a ‘Quick Start’ guide to begin with. Sorry I haven’t progressed this yet - been busy. Should be able to get onto it this week.

1 Like
26

Hi,

OK - Part 1 Introduction to Whonix stuff is finished. I’m now working through the Part 2 Whonix Installation section.

For this Quick Guide, do you want me to cover off the Qubes-Whonix templates installation (see link below) or just focus solely on KVM and Virtualbox i.e. standard (easy) virtualizer solutions?

Most newcomers to Whonix will not be looking for a Xen bare metal hypervisor solution in the first instance. Further, advanced users would just install templates via the Qubes 3.1 installer at set-up.

When I eventually get this v0.1 done, I’ll post it to a new thread. It might take a few weeks.

1 Like
27

Finished where?

Mention Qubes.

28

OK - will link to Qubes also.

I didn’t post the introduction, as I thought I would draft the document completely first.

29

I’ve made good progress on this and expect to have the complete draft posted within a few days, or a week at worst (fingers crossed).

If you end up liking it, I might have some time to move onto reworking the FAQ, or whatever else is a priority. We’ll see. Although I dare not tackle a ‘long version’ of the guide, as it would probably take months :grinning:

1 Like
30

@entr0py

About your previous post… splitting Whonix documentation into a short and long edition for better usability - #19 by entr0py

Could you please update it as per the comments that followed? splitting Whonix documentation into a short and long edition for better usability - #23 by Patrick

(Creating a new post.) That would help getting this task done.

1 Like
31

@entr0py I didn’t notice you revised the list by editing your post. Glad it’s already done! :slight_smile: I’ll quote it here:

    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
32

Unless there are further comments, I think this is ready to go.

33

Oh, some confusion. My first list was a proposed list of categories for the entire documentation section (knowledgebase).

What you just quoted was for the Quick-Start guide. On second thought, I think Section 1:

shouldn’t be included in the Quick-Start. There should be a link “What is Whonix?” on the main page and there should be a separate page dedicated to explaining what Whonix is; an overview of how it works; and a comparison to other systems.

So Quick-Start should jump straight to choosing, downloading, installing, and running. I’m thinking the target audience should be Windows/Mac/very new Linux users with little to no experience with Tor and little to no experience with VMs. So the goal is: accessibility, accessibility, accessibility. (also favor GUI over CLI wherever possible) Start with basic security/privacy and give them the path to advance further if inclined. I’ll try to write some prose this weekend.

[note to self: post-install: receive important news, stay updated.]

1 Like
34

This thread is getting crowded. Difficult to grasp.

Too many terms. Quick start, entire documentation, full documentation.

But I guess we’re all somewhat on the same page. And any change is probably better than the overwhelming thing.

There are quite some drafts now…

“full documentation” (the “legacy”, we can rename/move this):
Whonix ™ Documentation

“entire documentation”:
splitting Whonix documentation into a short and long edition for better usability - #10 by entr0py

Proposed Categories ?:
splitting Whonix documentation into a short and long edition for better usability - #16 by entr0py

Quick-Start:
splitting Whonix documentation into a short and long edition for better usability - #31 by Patrick

Right?

What’s next? I mean, someone still seeing through this and wanting to take the lead on this one? :slight_smile:

35

Right. This thread needs to be split into a short and long edition… :wink:

Please disregard splitting Whonix documentation into a short and long edition for better usability - #10 by entr0py. That was a draft for the Quick-Start guide which I realized was way too long.

The Goal is to have 2 things when all is done.

  1. The existing documentation stays in its current form. It could use a general editing pass to remove obsolete information, merge duplicated info, etc. It should also be re-categorized into meaningful categories (instead of having half the entries in “Advanced Topics”). Proposed categories.

  2. Quick-Start guide. Proposed outline.

@torjunkie’s guide falls into a category of its own. The issue with a document that is that comprehensive is that it becomes difficult to maintain over time because you forget what’s in it. Hence, keeping it disaggregated like the current wiki makes more sense IMO. However, it seems like it would be a waste not to offer it somewhere…

Since @torjunkie is busy at the moment, I will take pieces of his guide and put together a Quick-Start draft. Hopefully, he’ll have time to review it with his excellent writing skills! Also, I don’t know how to make web pages, so once the content is finished, perhaps @Ego can port it to the web platform.

EDIT: Speaking of the web platform, does the current engine allow for collapsible text without javascript? It’d be nice to direct readers to additional links for further information, but only if they can be hidden behind a click.

1 Like
36

Good day,

Porting/Incorporating any documentation once done shouldn’t be an issue, seing how most of the “Quick-Start-Documentation-Base-Code” seems to be working fine at the current moment from my point of view.

Is possible thanks to CSS, though strange. What I mean by that is that, from what I can tell (and read on Stack Overflow, etc) all more or less known CSS based “Expandable Text solutions” either don’t work with certain renderers, mess up the apperance of the rest of the site or at the very least aren’t persistent with one another, meaning that due to the nature of CSS (or rather the input feature “abused” for this), once you open one and then open another one, the first one will be closed regardless of the fact the user actually didn’t close it. On some renderers, this “persistence issue” seems to go so far as to once a user clicks anywhere on the site, the “expanded text field” closed.

Keeping in mind however, that all of this isn’t really that big of an issue compared to the alternative of never giving additional information, if the user desires it, during the initial introduction/learning fase, I feel compelled to say this as a reason for not using such a solution.

Have a nice day,

Ego

37

Sounds all great!

Should the Quick-Start guide be a table of contents that,

  • a) a table of contents that, links to all content
  • b) all Quick-Start guide content one one page?

I guess a) is better.

Where to add the Quick-Start guide?

  • a) mediawiki
  • b) new Whonix homepage “EgoBits1”

a) is easy. Could be done very soon.

b) might require concluding the mediawiki replacement thread first.

Ha! Good one! :slight_smile: