User help wiki pages need to be updated for Mate

BTW I think it would be good practice when creating or updating a user help wiki page to include a short note at the top about which version(s) of Trisquel it's targeted at. Ideally this would be a template as well, which would allow us to get lists of obsolete pages that need updating when a version reaches end-of-life, or there is a major UI change like a new DE (eg GNOME > Mate).

Great question. I think we need to define a documentation structure, either by Wiki or another tool. So we can think of a process of updating the documentation according to the version of the user.

Example, currently it looks like this:

 /wiki/disabling-orca-screen-reader 

It could have a documentation root and version of trisquel, to then enter the structure of a specific documentation. Even if this generates "duplicate work" you could use the redirect feature for the same content. Like this:

 /wiki/en/docs/8.0/accessibility/disabling-orca-screen-reader 

So one of the tasks is to review the current documentation and reorganize it in an accessible way, proposing a structure that can be followed for future versions.

Can you propose a structure for our documentation?

> A lot of user help wiki pages still reflect the user experience on GNOME Fallback, for example this page instructing users on how to disable Orca:
> https://trisquel.info/en/wiki/disabling-orca-screen-reader

I actually wrote this page specifically for the new Flidas users who were confused by the screen reader. All screenshots are from and all instructions apply to Flidas/MATE. However, I agree in general that we should keep the instructions current, and there is no point in retaining information about GNOME Fallback now that Belenos has reached EOL.

Here is an excerpt from something I wrote a while back about how I would like to restructure the documentation. I found it too hard to implement these ideas with the current Wiki structure, and because with the current website all changes are live immediately (no way to work offline and merge) I did not feel comfortable making any sweeping changes.

Anyway, here are some ideas that I think would make the documentation more useful and more maintainable:

First, ensuring that all manuals provide a graphical guide. Windows and macOS users are used to being able to navigate their entire system without a terminal. Most have no idea what a terminal is. It is also possible to navigate Trisquel without a terminal, but you wouldn't know that from some documentation pages. Having documentation that relies on terminal commands reinforces the perception that GNU/Linux is only for hackers and that "normal" people should use a proprietary system. I think that using terminal commands in explanations (especially in the forum) is popular is that they work with any desktop environment. Trisquel officially supports multiple desktop environments, so the documentation should be desktop-agnostic. Here is how I propose achieving this by making the documentation much more modular.

Many guides have steps that are similar to each other. For example, many guides require the user to install a package. They usually instruct the user to run 'sudo apt install package' in a terminal, because it would take up too much space to explain how to use Add/Remove Applications or Synaptic. Instead, we can say "Install the package [package]. (see "Installing and Removing Packages)" and link to this page[8]. Also, in guides that explain how to do something with a terminal, instead of saying "Open a terminal with Crtl+Alt+T" (which might not ever work in some desktop environments) and warning the user about the risks of using the terminal, we can say "In a terminal (see "Introduction to the Command Line")..." and link to this page[9], which should have the content of this page[10] at the top so that users see the warning first.

[8]https://trisquel.info/en/wiki/installing-updating-and-removing-software
[9]https://trisquel.info/en/wiki/introduction-command-line
[10]https://trisquel.info/en/wiki/never-simply-copy-and-paste-commands

To make the documentation desktop-agnostic, there should be a page for each common desktop environment (Trisquel/MATE, Trisquel Mini/LXDE, GNOME, Xfce, etc.) containg a section for each task or feature that varies among desktop environments (Navigating your System, Window Managment, Workspaces, Launching Programs, Keyboard Shortcuts, Configuration, etc.). The pages would be in a "Graphical User Interface" branch under "Home and Office" along with a guide on installing and switching desktop environments. However, each task (Navigating, Window Managment...) will also have it's open page that either embeds or links to the corresponding section for each desktop environment. That way, when a guide requires the user to do one of these things, rather than explaining how to do so in a way specific to one desktop it can link to the relevant page. As long as the page for each desktop environment is complete, none of the other documentation pages will have to be specific to one DE. Occasionally a guide might have to provide several menu paths for different desktop environments, but by linking to a "Launching Programs" page there will be no need for a screenshot clarifying when the meny path is referring to.

[11]https://trisquel.info/en/wiki/installing-updating-and-removing-software

chaosmonk:
> All screenshots are from and all instructions apply to Flidas/MATE.

Including the first picture, depicting a top menu bar that looks like something out of Ubuntu and that I've never seen in any Flidas/Mate install? I saw this and immediately assumed the rest of this page was out-of date too. Oops! ;)

I agree with having generic instructions for things like installing packages and linking to them, rather than trying to include them in every help page that instructs the user to install a package. I also agree that help pages need to start with the simplest, graphical way of carrying out a task, although I do think it's good to include the command line method that does the same thing at the bottom of each help page. It's a disservice to new users to hurl them straight into the CLI, but it's just as much a disservice to leave intermediate users trapped in inefficient GUI land.

Installing a non-default DE requires at least an understanding of how to use Synaptic, if not basic CLI skills, so that assumes an intermediate user who is probably capable of finding help elsewhere with the DE they've chosen. I'm not opposed to having help pages for every DE in the Trisquel repos, complete with screenshots, but it would be a tremendous amount of work to create these and keep them up-to-date. Can I suggest that for now, we focus on creating a complete, up-to-date and thoroughly tested set of help pages for Flidas/Mate, Flidas/LXDE, Etiona/Mate, and any other flavours Etiona is released in? Once we've achieved that, we can evaluate how much work is was, and consider whether we want to add help pages for more DEs.

> Including the first picture, depicting a top menu bar that looks like something out of Ubuntu and that I've never seen in any Flidas/Mate install?

The screenshot was definitely taken in Flidas, but it was around the time that Flidas was first release, so it's possible that there was a change to the LightDM defaults after that.

> I also agree that help pages need to start with the simplest, graphical way of carrying out a task, although I do think it's good to include the command line method that does the same thing at the bottom of each help page.

Yes, I think describe it both ways, so that if desired they can gradually get used to doing things with the terminal (when they realize how much faster it is).

> Can I suggest that for now, we focus on creating a complete, up-to-date and thoroughly tested set of help pages for Flidas/Mate, Flidas/LXDE, Etiona/Mate, and any other flavours Etiona is released in?

I think that containing all of the DE-specific stuff contained to one-page-per-DE will greatly improve maintainability. To add support for a DE, only one new page needs to be written, and if we want to update the screenshots for a new version of Trisquel we'll know exactly where the images to replace are located. I agree though that we should start with official Trisquel flavors (MATE and LXDE).

I don't think we need separate pages for Flidas/MATE and Etiona/MATE, since most of the information should be the same. Maybe we could have screenshots from both next to each other if there are any differences.