Project

General

Profile

Feature #14589

Feature #14568: Additional Software Packages

Write user documentation for Additional Software feature

Added by u 10 months ago. Updated 3 days ago.

Status:
In Progress
Priority:
Normal
Assignee:
Category:
-
Target version:
Start date:
09/04/2017
Due date:
05/01/2018
% Done:

33%

QA Check:
Dev Needed
Feature Branch:
doc/14589-additional-software
Type of work:
End-user documentation
Blueprint:
Starter:
Affected tool:
Additional Software Packages

Description

This should happen before May 1st 2018. (B6)
It needs to happen so early because we still need time to conduct the user testing and fix remaining bugs.

The "If you are offline […]" hint on https://tails.boum.org/doc/first_steps/persistence/configure/#additional_software is probably outdated.

The persistence setup UI has changed a lot (see subtasks of #14595).

  • Update /doc/first_steps/persistence/configure and add icon
  • Fix icon of "Bitcoin Client" persistence feature (optional)
  • Update FAQ
  • Add screenshots
  • Update /doc/first_steps/persistence/configure to new UI of the persistence configuration
  • Update /doc/first_steps/persistence
  • Prepare release notes

Subtasks

Bug #14590: Mentor and review user documentation for Additional Software featureIn Progresssajolida

Feature #15260: Clarify what is Tails Greeter in the documentation of each additional settingResolved

Feature #15538: Change doc/advanced_topics/additional_software to reflect new ASP featuresResolved

Feature #15539: Reorder documentation with changes from #15280Resolved

Feature #15541: Change doc/first_steps/persistence/configure to reflect new ASP featuresIn Progresssajolida

Feature #15543: Give examples of nice software to install each timeConfirmedemmapeel

Feature #15558: Fix Bitcoin icon on Persistent configuration docsConfirmedsajolida

Feature #15559: ASP: Update /doc/about/features with more infoIn Progressemmapeel

Feature #15561: ASP: Prepare snippet for the release notesConfirmedemmapeel


Related issues

Blocked by Tails - Bug #14599: Release BETA for Additional Software feature/GUI Resolved 04/15/2018

History

#2 Updated by u 10 months ago

  • Related to Bug #14590: Mentor and review user documentation for Additional Software feature added

#3 Updated by u 10 months ago

  • Description updated (diff)

#4 Updated by u 10 months ago

  • Blocks Feature #14591: Conduct User Testing of Additional Software packages GUI added

#5 Updated by u 10 months ago

  • Description updated (diff)
  • Due date changed from 07/15/2018 to 05/15/2018

#6 Updated by intrigeri 10 months ago

Please consider using a target version that reflects the deadline: in my experience "Due date" doesn't work well to plan one's work.

#7 Updated by sajolida 10 months ago

  • Target version changed from 2018 to Tails_3.7

I need that done for the user testing, so aiming at May 1 (but could be a bit late).

#8 Updated by u 10 months ago

  • Due date changed from 05/15/2018 to 05/01/2018

#9 Updated by u 10 months ago

  • Description updated (diff)

#10 Updated by sajolida 5 months ago

Here are some wild notes that I took during the UX sprint and might be useful for writing the doc:

  • P2 was wondering where the software was installed. Trying to open it and remove it.
  • P3: « I could use Tails more if I had all the software I use. It would make everything I use more secure. »
  • P3 wondered if that would make her Tails one-of-a-kind and less
    anonymous. Tails is still the same, until you start and unlock your
    persistent storage. Since then we tried to clarify from the
    interface that the software was stored in the persistent storage.
  • P6: « You could install only what you need as a way of having less stuff on Tails in general and so better security. »

#11 Updated by u 4 months ago

  • Blocked by Bug #14599: Release BETA for Additional Software feature/GUI added

#12 Updated by intrigeri 4 months ago

  • Description updated (diff)

#13 Updated by intrigeri 3 months ago

  • Description updated (diff)

#14 Updated by emmapeel 2 months ago

  • Status changed from Confirmed to In Progress
  • Feature Branch set to emmapeel:doc/14589

#15 Updated by sajolida 2 months ago

  • Description updated (diff)

#16 Updated by sajolida about 2 months ago

I had a look at your branch today. Please check the improvements that I
pushed to doc/14589-additional-software. I also merged them into
feature/14594-asp-gui.

Regarding your questions and the rest of the work:

  • In the release notes, I try to reuse the screenshots from the doc if
    possible. So I have less work and less binary files in the Git repo.
  • I think the warning on top of "Configuring additional APT
    repositories" should be more scary because it could allow people to
    install, for example, Skype or Dropbox on their Tails. But I'm not sure
    how...
  • I think we should put the "Check" section before the "Remove" section.
    It would make sense in terms of the order in which people might want to
    perform the operations. Then it would also make it easier to mention the
    "Additional Software" configuration in the "Remove" section, and we
    should do that too.
  • We should mention in the relevant places that installing a package
    requires administration rights (and maybe that installing them
    automatically doesn't require one). I didn't test if you need an
    administration password to remove a package from the "Additional
    Package" configuration.
  • What about the work on the other pages? Do have a TODO list elsewhere
    for that?

#17 Updated by sajolida about 2 months ago

  • QA Check set to Dev Needed
  • Feature Branch changed from emmapeel:doc/14589 to doc/14589-additional-software

#18 Updated by emmapeel about 2 months ago

sajolida wrote:

...

  • I think the warning on top of "Configuring additional APT
    repositories" should be more scary because it could allow people to
    install, for example, Skype or Dropbox on their Tails. But I'm not sure
    how...

Yes, definitely. Also the other day one user in irc had problems because he thought it was needed to change the repos to install software, so I will edit it to make clear that it is not needed and also super dangerous (well, more dangerous than installing from the default repos)

  • What about the work on the other pages? Do have a TODO list elsewhere
    for that?

I was still using the pad we used...

#19 Updated by emmapeel about 2 months ago

sajolida wrote:

  • In the release notes, I try to reuse the screenshots from the doc if
    possible. So I have less work and less binary files in the Git repo.

Ok good so the place I chose was the correct.

  • I think we should put the "Check" section before the "Remove" section.
    It would make sense in terms of the order in which people might want to
    perform the operations.

That's 087bc4570b

Then it would also make it easier to mention the
"Additional Software" configuration in the "Remove" section, and we
should do that too.

that's 8a60a72e58

  • We should mention in the relevant places that installing a package
    requires administration rights (and maybe that installing them
    automatically doesn't require one).

As you cannot do anything on this page without and administration password, I added a note div on the top, advising that you need to add this password to do all the things mentioned on the page, see 248436da10

I didn't test if you need an
administration password to remove a package from the "Additional
Package" configuration.

Yes, you need an administration password to remove a package from the Additional Package config. But the remove button appears anyway. You get asked for the amnesia password, and also: it does not say anything about restarting Tails and adding it at boot. Shall I open a ticket about this?

  • What about the work on the other pages? Do have a TODO list elsewhere
    for that?

There are some subtickets to this one, and some TODOS on the pad. I want to move the pad complicated stuff to tickets later today, and fix the simple ones.

#20 Updated by sajolida about 2 months ago

I was still using the pad we used...

I've seen that but, going through the pad again, I thought that it was
only about /doc/first_steps/additional_software but not about the rest
of the changes that we might still have to do in other places.

Can you double check with the post-its on your wall whatelse there is to
do outside of this page?

#21 Updated by sajolida about 2 months ago

  • Blocks deleted (Feature #14591: Conduct User Testing of Additional Software packages GUI)

#22 Updated by u about 2 months ago

Can one of you please point me to the place where I can find the documentation? I want to send out a call for testing ASAP and add this information to it. If I don't get an answer early enough I will try to use the branch doc/14589-additional-software.

#23 Updated by u about 2 months ago

BTW this branch doc/14589-additional-software does not merge cleanly with master, can you please fix that?

#24 Updated by bertagaz about 1 month ago

  • Target version changed from Tails_3.7 to Tails_3.8

#25 Updated by sajolida about 1 month ago

I reviewed everything we did so far and here is a list of pending issues (except pending work on subtasks of this ticket):

  • Please use the GNOME icon corresponding to the 'x' button.

    See git grep symbolic -- "*.*m*".

    The GNOME icons are in /usr/share/icons/gnome.

  • List removing through X button in Additional Software as the first
    option because it's the simpliest and quickest.
  • Should we move "After the package is removed" as part of "Synaptic"?
    Because this notification doesn't appear when clicking the X button
    in Additional Software. I think that moving it below Synaptic would
    help people understand that it won't appearing when clicking the X
    button in Additional Software.
  • I don't think we should add "Install additional software" to
    /doc/first_steps/persistence.mdwn as you did in 144442db02 because
    in the general index it's not a subpage of it.
  • Please explain the need for the admin password right at the place
    where it is needed (instead or in addition to your note): when
    adding and removing software (but not to use them). During the user
    testing I saw how people scan these instructions and your note on
    the top of the page wouldn't be helpful for them.

    For example, write "When starting Tails, [[set up an administration
    password|doc/first_steps/startup_options/administration_password."
    as first step.

    You could even add step to enter the administration password.

  • The warning on top of "Configuring additional APT repositories" is
    still not scarier.
  • We already have a ticket about improving the UX when no admin
    password is set: #9554. No need to create a new one.
  • Mention Dotfiles. Maybe as a tip for advanced users. Because I don't
    expect Dotfiles to make sense or be able to use by people who are
    not advanced Linux users.

I also pushed a bunch of fixes. Make sure to fetch
origin/doc/14589-additional-software.

#26 Updated by sajolida about 1 month ago

Please reassing this ticket to me once you think that all issues are solved.

I'll refrain from reviewing your work again until then.

#27 Updated by emmapeel 18 days ago

sajolida wrote:

I reviewed everything we did so far and here is a list of pending issues (except pending work on subtasks of this ticket):

Thanks for your thorough review.

  • Please use the GNOME icon corresponding to the 'x' button.

I've done that in 411968a695. I thought better to keep the long icon name, because it was the original name on the icons directory.

  • List removing through X button in Additional Software as the first
    option because it's the simpliest and quickest.

That's 94ba0c7e08.

  • Should we move "After the package is removed" as part of "Synaptic"?
    Because this notification doesn't appear when clicking the X button
    in Additional Software. I think that moving it below Synaptic would
    help people understand that it won't appearing when clicking the X
    button in Additional Software.

I left it at the end, so now it comes after Synaptic and apt, which also triggers
that window.

  • I don't think we should add "Install additional software" to
    /doc/first_steps/persistence.mdwn as you did in 144442db02 because
    in the general index it's not a subpage of it.

I found that link when moving the links that pointed to the original
feature, but I left if because I though people will maybe look for
something about Additional Software there. I have taken it out with
28a782d938

  • Please explain the need for the admin password right at the place
    where it is needed (instead or in addition to your note): when
    adding and removing software (but not to use them). During the user
    testing I saw how people scan these instructions and your note on
    the top of the page wouldn't be helpful for them.

Yeah I saw this feedback too. I add it as first step where is needed with
3f283bd9ab

  • The warning on top of "Configuring additional APT repositories" is
    still not scarier.

I did my best on b0fd3f5b1c

  • We already have a ticket about improving the UX when no admin
    password is set: #9554. No need to create a new one.
  • Mention Dotfiles. Maybe as a tip for advanced users. Because I don't
    expect Dotfiles to make sense or be able to use by people who are
    not advanced Linux users.

Added a note with d4a055d43b. I think a lot of non-technical people is
going to be in need of a dotfiles link, but they may not even know it.
ref: Bug report: 19ce6424149c31e34a63f2b966df51b8

I also pushed a bunch of fixes. Make sure to fetch
origin/doc/14589-additional-software.

Cool! I like contractions too!

Also available in: Atom PDF