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

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

38

Good day,

I feel like regarding that, it would be necessary to really come to an agreement in regards to certain aspects. After all, most requirements we agreed on previously in that or other threads have already been achived in one way or another.

Let’s go through them one by one:

How does the new solution make sure translated pages do not get out of sync? I.e. when the English original is modified, how is this change reflected or at least noted on the translated version?

Well, similarly to Mediawiki, not at all really. Since Mediawiki has always kept the translated pages and the original fairly seperate, that has been what I set out to achieve as well. With Github as the base, and some tinkering with Jekyll, it seems to work, for now.

Can we make it pretty? Usable, modern presentation?

In the “New Website Thread”, I have already demonstrated and discussed a few designs. Whether these are presentable enough however, would have to be decided, as well as the question, which of the many mock-ups/attempts now should be used (i.e. categories on the side, long page, etc).

Can we have a mostly imported migration process from the old to the new wiki?
What about internal links?
What about wiki templates?
What about special markup such as {{Code2|…}} etc?

Since this is mainly being discussed for the short documentation, this question isn’t really important for this discussion.

Can we add meta tags (for seo, social media)? (Example below.)

There are different ways to achieve this with Jekyll, however I didn’t really test any at the current point in time.

Regarding things like “Expand buttons”, to enhance documentation, I already wrote about that in the post above.

Have a nice day,

Ego

39

Alright.

I think we concluded, sitebar is fine.

How can we decide which mock-up to use? I guess the overview is now done… It’s sill in the git history, though. Could you show these mock-ups overview please so we can pick one?

Ok.

So we’d just use the new homepage for Quick-Start table of contents, linking to the wiki. Why not…

Yes. The “mediawiki way”, collapsed by default when using javascript and expandable. And without javascript, everything is expanded by default. I guess that is the best compromise we can make at this time until css provides better ways.

40

Good day,

Sure, will create comparison screenshots right away.

I apparently seem to not have properly expressed myself in the previous post. “Expandable text” is possible with CSS without necessitating JS in any way. It just isn’t as versatile and dependable as JS based solutions under certain engines, though it should work fine. Example: https://codepen.io/peternguyen/pen/hICga/

Have a nice day,

Ego

1 Like
41

I did understand that earlier. :slight_smile: I however discarded that option, because you said…

Well, if it was only as bad as auto expanded by default, that would be a compromise we could make. (Similar to the one with our existing mediawiki solution.)

I understood this as a deal breaker.

That seems very buggy indeed. A deal breaker?

Which could be super annoying if someone wants to copy something from an expanded area, no?

42

It’s looking great! I assume it would be trivial for you to make it hidden by default and expand upon click? Could you modify that example please to make two boxes hidden by default so we can test this?

43

Good day,

Ah, I see. Well, I can see why you see these things as issues, though let me clarify a bit which engines are problematic with such a set-up. The more severe issues, like messing up the base layout or collapsing at any click regardless of where it is made, should only be expected to happen on browsers like the Internet Explorer 8, due to its rather obscure implementation of CSS.

The persitence issue is however one which indeed happens regardless of browser, as shown in these small examples: javascript - Show hide divs on click in HTML and CSS without jQuery - Stack Overflow As you can see, most of the shown examples are plagued with this problem. The top one seems to work on Blink at least without fault. Adding to that, there seem to be other, more advanced approaches which, at least from what I can tell, seem to work much more reliable like this one: http://jsfiddle.net/thurstanh/emtAm/2/

Yes, would be possible easily as well, though this approach suffers from the “persitence issues”, whereas the last example I linked doesn’t making it a much better choice as a base.

Have a nice day,

Ego

1 Like
44

Good day,

Regarding the previous request to show the two different, basic concepts for the Quick-Start-Guide:

whonix1.PNG2209×1498 134 KB

The advantage of going this route is, as I’ve previously explained, that users get gradually thought everything neceassary to operate Whonix, rather than in one session, making the whole “ordeal” easier to digest. Arguments against it have been that this approach isn’t really of use considering users likely click" through the whole thing in one go eitherway since they want to use Whonix to its fullest immediately. Adding to that, finding what you are looking for might be harder than with an “one-page-solution”. However, I personally feel that a chapter based approach makes a project look better, though that is likely just me.

whonix2.PNG2410×1524 190 KB

The advantages of a “one-page-concept” with click- and linkable subcategories is rather obvious. It’s easier to maintain, let’s users find information more quickly and efficiently and all in all is very similar to what we currently have on MediaWiki on sites like “DoNot”. Different to those however, to save screenspace, it was (at least at the time) decided against having the chapters on top or the site of the page. This might make finding your way arround as a newcomer harder. However, since newcomers should be reading the entire thing anyways, this shouldn’t be a deal breaker. Having one long, ongoing page also means that we should try to keep the information as focused, short and simple as is humanly possible, otherwise we (as I’ve mentioned in detail before) may overwhelm users with so much information that they wouldn’t want to use Whonix in the first place or (even worse) underwhelm them so much that they immediately presume all that information isn’t necessary and is already something they know. Both states we should avoid, as far as I’m concerned.

Have a nice day,

Ego

1 Like
45

Ego:

2209×1498 134 KB

The advantage of going this route is, as I’ve previously explained, that users get gradually thought everything neceassary to operate Whonix, rather than in one session, making the whole “ordeal” easier to digest. Arguments against it have been that this approach isn’t really of use considering users likely click" through the whole thing in one go eitherway since they want to use Whonix to its fullest immediately. Adding to that, finding what you are looking for might be harder than with an “one-page-solution”. However, I personally feel that a chapter based approach makes a project look better, though that is likely just me.

Since there weren’t any other opinions… And since we previously agreed
that sidebar is okay… Let’s go for that route.

46

Good day,

Ok, will copy it into the stable branch together with the new changes for the newsletter as soon as possible. Should I integrate the list’s headings and subheadings as well?

Have a nice day,

Ego

47

Ego:

Should I integrate the list’s headings and subheadings as well?

What do you mean by that?

48

Good day,

The small list which was create by @entr0py and can be found in post #31.

Have a nice day,

Ego

49

Post #31 for sure? There is no list in that post.

50

Good day,

Yes, I’m talking about this one:

list.PNG1879×1030 95.1 KB

Have a nice day,

Ego

51

That is #31 btw.

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

That list is fine for the sidebar, I guess?

Not sure about the sub headings. Any opinions?

52

Hi Patrick (and everyone else),

I think the headings and sub-headings are fine for now, if we want to imitate a ‘Tor Browser’ manual style short guide. Sweet and simple (the KISS principle).

As @entr0py progresses, it will become clear whether anything else is needed. I think the Qubes-Whonix vs Whonix separation I originally did may or may not need to be imitated, even in a short version.

I’m happy to edit this as entr0py nuts it out. I also agree this thread is far too long. So, I’ve started a new thread for the short version where only entries and suggested edits should happen. I’ve cut and pasted entr0py’s suggested ToC.

If we get our shit together, this might even get done for Christmas! :wink:

3 Likes
53

For purposes of closing ticket ⚓ T521 simplify https://www.whonix.org/wiki/Documentation…

Is this subject considered done or is there something else to do?

54

Over 3 years old - just kill it off. It can be resuscitated later on if needs be.

1 Like
55

Not exactly this but big progress was made.

2 Likes