Opened 4 years ago

Last modified 6 months ago

#10974 assigned project

Turn the “short user manual” into the Tor Browser User Manual

Reported by: lunar Owned by: lunar
Priority: Medium Milestone:
Component: Applications/Tor Browser Version:
Severity: Normal Keywords: tbb-usability, SponsorO
Cc: mttp, phoul, Sherief, mrphs, kelley, gk, mcs Actual Points:
Parent ID: Points:
Reviewer: Sponsor:

Description

As discussed during the 2014 winter dev. meeting, we want to turn the “short user manual” into the Tor Browser User Manual.

Key differences:

  • The Tor Browser User Manual will be shipped with the Tor Browser.
  • The TBB team will be responsible for ensuring that the manual is up-to-date: new features that affect the user experience are required to update the manual before being merged.
  • The Tor Browser User Manual will contain a list of known issues.
  • The Tor Browser User Manual will not explain how to download and verify the Tor Browser (if you are reading it, it means that you are either able to reach the Tor website or that you already have the Tor Browser).

Child Tickets

TicketStatusOwnerSummaryComponent
#5294newMake human summary of TBB design docApplications/Tor Browser
#5811newrunaReview the latest set of changes in the “short user manual”Applications/Tor Browser
#8779closedrunaDiscuss possible improvements to the short user manualUser Experience/Tor Support
#10534closedmikeperryLet's not advertise help desk emails directlyApplications/Tor Browser
#10975closederinn, nickm, Sebastian, weaselPlease create a Git repository for the Tor Browser User ManualInternal Services/Service - git
#10976closedPlease create a LDAP account for mttpInternal Services/Tor Sysadmin Team
#10978closedlunarDecide on a source format for the Tor Browser User ManualApplications/Tor bundles/installation
#10980newBuild the Tor Browser User Manual when build the Tor Browser BundleApplications/Tor bundles/installation
#10981closedmttpWrite a “how to get support?” section in the Tor Browser User ManualApplications/Tor bundles/installation
#11020closedMake LDAP account for Nima Fatemi (mrphs)Internal Services/Tor Sysadmin Team
#11652newReview text of Tor Browser User ManualApplications/Tor bundles/installation
#11698newDecide how to incorporate Tor Browser Manual pages into Tor BrowserApplications/Tor Browser

Change History (19)

comment:1 Changed 4 years ago by lunar

Keywords: SponsorO added

comment:2 Changed 4 years ago by lunar

Type: defectproject

comment:3 Changed 4 years ago by gk

Cc: gk added

comment:4 Changed 4 years ago by erinn

Owner: changed from erinn to lunar
Status: newassigned

comment:5 Changed 4 years ago by lunar

Status: assignedaccepted

comment:6 Changed 4 years ago by lunar

The latest incarnation of the “short user manual” is #5811. Content of the Tor Browser User Manual should be taken from there.

comment:7 Changed 4 years ago by mrphs

Cc: mrphs added; nima removed

comment:8 Changed 4 years ago by mcs

Cc: mcs added

comment:9 Changed 4 years ago by lunar

Mallard has been chosen as the documentation format.

Next step is to start populating the Git repository.

comment:10 Changed 4 years ago by mttp

I've pushed the start of a user manual to https://gitweb.torproject.org/tor-browser/user-manual.git

Right now the pages must be opened with yelp. I have not yet added a Makefile that would allow the pages to be built to html format.

I've only made an 'en_US' directory so far. The strings on all but one of these pages have been written from scratch and will need to be localized. Do I need someone to give me some sort of transifex privileges in order to enter the strings in transifex for translation, or can I just make myself a transifex account and add them?

Right now the documentation has 5 screenshots that will need to be localized. I am completely fine with doing this work for all languages. Documentation, in general, should minimize the use of screenshots, but based on my interactions with end users, I can foresee screenshots providing meaningful additional benefit and reducing confusion more than word descriptions alone would.

Last edited 4 years ago by mttp (previous) (diff)

comment:11 Changed 4 years ago by phoul

Once the English version of the manual has been reviewed / edited, another ticket should be opened with the component set to "translation". This ticket should include a link to the English strings in git, and then I will add the strings to Transifex for translation.

Adding the strings before the document has been reviewed should generally not be done, as it would result in wasted work for the translators as we review / edit / expand the document.

comment:12 in reply to:  10 Changed 4 years ago by lunar

Replying to mttp:

I've pushed the start of a user manual to https://gitweb.torproject.org/tor-browser/user-manual.git

Thank you for kicking off the effort.

(For the record, I won't be able to do any proper contribution before next week.)

Right now the documentation has 5 screenshots that will need to be localized. I am completely fine with doing this work for all languages. Documentation, in general, should minimize the use of screenshots, but based on my interactions with end users, I can foresee screenshots providing meaningful additional benefit and reducing confusion more than word descriptions alone would.

For those who haven't read it, here are GNOME recommendations about screenshot:
https://developer.gnome.org/gdp-style-guide/stable/infodesign-8.html.en#infodesign-10

A StackExchange answer that feels insightful:
http://writers.stackexchange.com/a/10646

comment:13 in reply to:  10 Changed 4 years ago by lunar

Replying to mttp:

Right now the documentation has 5 screenshots that will need to be localized. I am completely fine with doing this work for all languages. Documentation, in general, should minimize the use of screenshots, but based on my interactions with end users, I can foresee screenshots providing meaningful additional benefit and reducing confusion more than word descriptions alone would.

Updating included media will require Git access in any cases.

comment:14 Changed 4 years ago by lunar

Owner: changed from lunar to mttp
Status: acceptedassigned

Suddently, Matt is leading this. So updating the ticket.

comment:15 in reply to:  14 Changed 4 years ago by mttp

Owner: mttp deleted

Replying to lunar:

Suddently, Matt is leading this.

Thanks, but I don't feel comfortable taking on this role.

comment:16 Changed 4 years ago by lunar

Owner: set to lunar

comment:17 Changed 4 years ago by erinn

Keywords: needs-triage added

comment:18 Changed 4 years ago by erinn

Component: Tor bundles/installationTor Browser
Keywords: needs-triage removed

comment:19 Changed 6 months ago by teor

Severity: Normal

Set all open tickets without a severity to "Normal"

Note: See TracTickets for help on using tickets.