Project

General

Profile

Feature #12026

Document OnionShare

Added by sajolida almost 3 years ago. Updated almost 3 years ago.

Status:
Resolved
Priority:
Normal
Assignee:
-
Category:
-
Target version:
Start date:
12/09/2016
Due date:
% Done:

100%

Feature Branch:
spriver:web/12026-document-onionshare
Type of work:
End-user documentation
Blueprint:
Starter:
Affected tool:

Associated revisions

Revision 5da33b0e
Added by intrigeri almost 3 years ago

Merge remote-tracking branch 'spriver/web/12026-document-onionshare' into testing

Fix-committed: #12026

History

#1 Updated by intrigeri almost 3 years ago

Please tell me once the code is ready and merge into devel so I can try it out.

FWIW the code review process is almost over, and I don't expect anything user-visible to change as a result of it.
But I didn't even try using OnionShare from that branch yet.

#2 Updated by intrigeri almost 3 years ago

Oops, I didn't notice that this was a subtask of #7870, and merged the branch for OnionShare, that was assigned to me for QA, without waiting for the doc to be ready. Sorry!

#3 Updated by sajolida almost 3 years ago

  • Assignee deleted (sajolida)

#4 Updated by intrigeri almost 3 years ago

  • Target version changed from Tails 2.10 to Tails_2.11
  • Parent task deleted (#7870)

#5 Updated by spriver almost 3 years ago

  • Assignee set to sajolida
  • QA Check set to Ready for QA
  • Feature Branch set to spriver:web/12026-document-onionshare

I just finished my documentation bits for OnionShare. I tried to keep it simple, as the application itself is not that complicated.

#6 Updated by intrigeri almost 3 years ago

  • Assignee changed from sajolida to intrigeri

:)

#7 Updated by intrigeri almost 3 years ago

  • Target version changed from Tails_2.11 to Tails 2.10

#8 Updated by intrigeri almost 3 years ago

  • Status changed from Confirmed to In Progress
  • % Done changed from 0 to 50

#9 Updated by intrigeri almost 3 years ago

  • Assignee changed from intrigeri to spriver
  • QA Check changed from Ready for QA to Dev Needed

Hi! This looks good and one could argue it should be merged as-is (it's much better than no documentation at all), but as always, let's be kind to our translators, and try to polish the text before it lands on their plate :) So here's the deal: if you think you can improve the branch, based on my feedback, by the end of the week, please go ahead and I'll promptly review'n'merge your final version; if you don't have time to work on that again this week, let me know, and I'll merge this branch, but will leave the ticket open and postpone it to 2.11, to indicate that a little bit more work is needed. OK?

  • One can see that you've put a lot of care into maintaining phrasing and styling consistency. Thanks, and congrats!
  • Maybe we should add OnionShare to the "features" page?
  • We generally avoid calling things we ship as "secure", since it doesn't mean much without a proper threat model etc.
  • s/Tor Network/Tor network/
  • typo in "Anyonone"
  • "who you disclose the address to" could be simplified with "you give the address"
  • maybe drop "who has access to the Tor network" and replace "Anyone" with "Any Tor user"
  • "files or folders", "files and folders": IMO we should say that in the intro (done already) and then only say "files" everywhere else
  • "the file browser" may need a proper application name and the corresponding styling; not sure how we do it everywhere else, please check and maintain consistency
  • I'm not sure it's worth it to document the 3 ways one can share files; sadly, we can't only document the right-click action, since it starts a new OnionShare every time; so perhaps document only the two Files-based actions: right-click for the first set of files, then drag'n'drop for the next ones. This way, we can:
    • turn the bullet list into a list of steps, with steps that would essentially be: 1. start Files; 2. right-click → "Share with OnionShare"; 3. if you want to add more files to the share, drag'n'drop them; 4. decide if you want to allow multiple downloads; 5. "Start sharing"; 6. give the address to anyone you want
    • drop the "to start OnionShare" paragraph, that seems misplaced (above the TOC) anyway
    • drop the Add Files / Add Folders method
    • drop the section titles and TOC, since in the end we just have a list of steps
  • s/will become/becomes/ (stick to the present tense when feasible)
  • "the link for sharing the files will become unavailable for anyone" feels a bit too abstract (and actually not very correct) ⇒ maybe "Once you close OnionShare or shut down Tails, the files are not shared anymore"?

#10 Updated by spriver almost 3 years ago

  • Assignee deleted (spriver)
  • QA Check changed from Dev Needed to Ready for QA

I now pushed my changes. Besides your proposals I did some improvements wrt grammar and style.

intrigeri wrote:

  • One can see that you've put a lot of care into maintaining phrasing and styling consistency. Thanks, and congrats!

Thanks! (:

  • Maybe we should add OnionShare to the "features" page?

Done.

  • We generally avoid calling things we ship as "secure", since it doesn't mean much without a proper threat model etc.

Understood and removed it. I've been already unsure about that when writing the first version. I only added it because https://onionshare.org is saying "that lets you securely and anonymously share".

  • s/Tor Network/Tor network/

Applied.

  • typo in "Anyonone"

Fixed.

  • "who you disclose the address to" could be simplified with "you give the address"

Applied.

  • maybe drop "who has access to the Tor network" and replace "Anyone" with "Any Tor user"

Applied.

  • "files or folders", "files and folders": IMO we should say that in the intro (done already) and then only say "files" everywhere else

Now it only says "files and folders" in the step for adding file, because in that step you actually add files or folders. Everywhere else it's now just files.

  • "the file browser" may need a proper application name and the corresponding styling; not sure how we do it everywhere else, please check and maintain consistency

The term "file browser" is used pretty often in the documentation (e.g. persistence section). I now included a link to doc/first_steps/introduction_to_gnome_and_the_tails_desktop#nautilus

  • I'm not sure it's worth it to document the 3 ways one can share files; sadly, we can't only document the right-click action, since it starts a new OnionShare every time; so perhaps document only the two Files-based actions: right-click for the first set of files, then drag'n'drop for the next ones. This way, we can:
    • turn the bullet list into a list of steps, with steps that would essentially be: 1. start Files; 2. right-click → "Share with OnionShare"; 3. if you want to add more files to the share, drag'n'drop them; 4. decide if you want to allow multiple downloads; 5. "Start sharing"; 6. give the address to anyone you want

Did this. The page looks now a lot cleaner (:

  • drop the "to start OnionShare" paragraph, that seems misplaced (above the TOC) anyway

Done (see above).

  • drop the Add Files / Add Folders method

Applied and

  • drop the section titles and TOC, since in the end we just have a list of steps

applied, too.

  • s/will become/becomes/ (stick to the present tense when feasible)

Right! (: Applied

  • "the link for sharing the files will become unavailable for anyone" feels a bit too abstract (and actually not very correct) ⇒ maybe "Once you close OnionShare or shut down Tails, the files are not shared anymore"?

Sounds a lot better.

#11 Updated by intrigeri almost 3 years ago

  • Assignee set to u

Great! u, you volunteered to do this review, maybe you want to follow-up on my initial review + the changes spriver did?
I think the deadline for merging (into the testing branch) is Monday, noon CET. If that doesn't work for you, just reassign to me :)

#12 Updated by intrigeri almost 3 years ago

  • Assignee changed from u to intrigeri

#13 Updated by intrigeri almost 3 years ago

  • Status changed from In Progress to Fix committed
  • Assignee deleted (intrigeri)
  • % Done changed from 50 to 100
  • QA Check changed from Ready for QA to Pass

Pushed a bunch of small improvements on top, merged!

#14 Updated by u almost 3 years ago

Assigning such a ticket to me on a Friday evening for monday noon might not work as expected, sorry. I just discovered this in my mailbox.

#15 Updated by intrigeri almost 3 years ago

Assigning such a ticket to me on a Friday evening for monday noon might not work as expected, sorry. I just discovered this in my mailbox.

Well, I had no particular expectations. That's the timeline we were working with and I was ready to take over if needed, which I did without hard feelings whatsoever. I'll try to be more careful next time I propose you to do something you volunteered for, if I realize that in practice it has to be done over the week-end :)

#16 Updated by intrigeri almost 3 years ago

Actually, I have rushed things a bit more than needed: I could very well have left on the 2.11 milestone (as I had postponed it on Thursday), instead of raising the bar and aiming for a merge in time for 2.10 (as I did on Friday). It's hard to balance "welcoming contributions from our new doc writer by ensuring her work is merged promptly" vs. "not creating stressful expectations for reviewers". I'll try to balance them better next time, sorry.

#17 Updated by anonym almost 3 years ago

  • Status changed from Fix committed to Resolved

Also available in: Atom PDF