Project

General

Profile

Bug #10934

Feature #7584: Update documentation for Jessie

Bug #8043: Update Disks documentation for Jessie

Update resetting with Linux for Jessie

Added by spriver almost 4 years ago. Updated almost 4 years ago.

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

0%

Feature Branch:
doc/10934-reset-linux
Type of work:
End-user documentation
Blueprint:
Starter:
Affected tool:

Description

The new GNOME version comes with GNOME Disks which contains a new GUI.

trailing.png View (44.4 KB) sajolida, 01/15/2016 03:51 PM

Associated revisions

Revision 2effc49b
Added by sajolida almost 4 years ago

Merge remote-tracking branch 'origin/doc/10934-reset-linux' (Closes: #10934)

Conflicts:
config/base_branch

History

#1 Updated by spriver almost 4 years ago

  • Feature Branch set to spriver:doc/10934-reset-linux

#2 Updated by sajolida almost 4 years ago

  • File trailing.png View added
  • Assignee changed from sajolida to spriver
  • QA Check changed from Ready for QA to Info Needed

Thanks for the branch. It's good to see more people writing doc!

Here are some first comments regarding the methodology:

  • You had config/base_branch set to "devel" so I guess you branched
    this out of devel. Now that RC1 has been release, you should branch
    your stuff from testing instead. I know this branch dance is
    complicated :)
  • Beware of trailing white spaces, see attachment. I highly recommend
    configure your Git to display colors by default. See #9130#note-12.
  • When rewritting anchors like you did for id="disk_utility" we should
    keep in mind that this might break external links. But here it's the
    first one on the page so I think it's no problem if we break any and
    you already fixed the only one inside tails.boum.org. So that's
    great.

Then regarding the content, why did you choose to document formatting the first partition only (through the double-gear button) and not formatting the whole disk (through the single-gear button)? I think formatting the whole disk would be a closer equivalent to the instructions we had previously?

Regarding the style to refer to these menus with icons (I hate them!), have a look at what we did for the installations instructions for Linux where we use Disks already:

https://tails.boum.org/install/linux/usb/

There we felt the need to put a screenshot of where the button was because some users mistook it for the "double-gear" and got into serious troubles. I'm not sure we should put the same screenshot in your doc but still reuse the same way of referring to this button.

I'm also going to ask GNOME for recommendations about this. I'll keep you updated :)

#3 Updated by intrigeri almost 4 years ago

  • You had config/base_branch set to "devel" so I guess you branched
    this out of devel. Now that RC1 has been release, you should branch
    your stuff from testing instead. I know this branch dance is
    complicated :)

Oops, good catch: I did the same mistake as spriver myself a few times since rc1 was released, so I think we'll merge devel into testing once more, so for this release cycle it's OK. And I doubt anyone will have time to review'n'merge stuff into devel that shouldn't go into 2.0 before the release :)

#4 Updated by spriver almost 4 years ago

  • Assignee changed from spriver to sajolida

sajolida wrote:

Thanks for the branch. It's good to see more people writing doc!

Here are some first comments regarding the methodology:

  • You had config/base_branch set to "devel" so I guess you branched
    this out of devel. Now that RC1 has been release, you should branch
    your stuff from testing instead. I know this branch dance is
    complicated :)

Okay, I didn't knew ;) but as intrigeri said I can keep it this way for this time?

  • Beware of trailing white spaces, see attachment. I highly recommend
    configure your Git to display colors by default. See #9130#note-12.

Did it. Thanks for the tip (:

  • When rewritting anchors like you did for id="disk_utility" we should
    keep in mind that this might break external links. But here it's the
    first one on the page so I think it's no problem if we break any and
    you already fixed the only one inside tails.boum.org. So that's
    great.

Got it. How can I find out about the external links? For our doc I can refer to the "Pages linking to this one"?

Then regarding the content, why did you choose to document formatting the first partition only (through the double-gear button) and not formatting the whole disk (through the single-gear button)? I think formatting the whole disk would be a closer equivalent to the instructions we had previously?

I honestly do not know why I chose to document it this way. Maybe I was thinking that some users would like to keep other partitions (e.g. persistent storage or LUKS partitions in general) I can of course change it to formatting the whole drive.

Regarding the style to refer to these menus with icons (I hate them!), have a look at what we did for the installations instructions for Linux where we use Disks already:

https://tails.boum.org/install/linux/usb/

There we felt the need to put a screenshot of where the button was because some users mistook it for the "double-gear" and got into serious troubles. I'm not sure we should put the same screenshot in your doc but still reuse the same way of referring to this button.

This is probably a good idea. IMHO the new UI is not really doc friendly. I can redo the screenshot, I'll be doing all Disks screenshots in the next days.

#5 Updated by spriver almost 4 years ago

  • QA Check changed from Info Needed to Ready for QA

Updated my branch. I now just used the corresponding icons and described the position (e.g. "in the top bar of the window"). Maybe this would be sufficient?

#6 Updated by sajolida almost 4 years ago

  • You had config/base_branch set to "devel" so I guess you branched
    this out of devel. Now that RC1 has been release, you should branch
    your stuff from testing instead. I know this branch dance is
    complicated :)

Okay, I didn't knew ;) but as intrigeri said I can keep it this way for this time?

Yeah, no big deal :)

How can I find out about the external links? For our doc I can refer to

the "Pages linking to this one"?

  • For links on our website I usually do git grep '#disk_utility' but
    "Pages linking to this one" should work too.
  • For links outside of our website, we can't really now what the
    Internet uses to point to our doc. For example in mailing list archives,
    maybe Redmine, random blogs, etc.

Then regarding the content, why did you choose to document formatting the first partition only (through the double-gear button) and not formatting the whole disk (through the single-gear button)? I think formatting the whole disk would be a closer equivalent to the instructions we had previously?

I honestly do not know why I chose to document it this way. Maybe I was thinking that some users would like to keep other partitions (e.g. persistent storage or LUKS partitions in general) I can of course change it to formatting the whole drive.

I think we should document formatting the whole stuff as you did know.

IMHO the new UI is not really doc friendly.

Yeah, you're on my side now!

I can redo the screenshot, I'll be doing all Disks screenshots in the next days.

There's no screenshot on this page and I don't think we need any.

So, I reviewed your work and added a bunch of nitpicking on top of it,
see c3248d1..5c0987d. I did super tiny commits to be as clear as
possible. Please don't be discouraged by the diff with your version.
This is how doc writing goes: you rewrite the same thing 2, 3, or 4
times entirely, clarifying and shortening it every time.

Please triple-check and then I can merge.

#7 Updated by sajolida almost 4 years ago

  • Status changed from New to Confirmed
  • Assignee changed from sajolida to spriver
  • Target version set to Tails_2.0
  • Feature Branch changed from spriver:doc/10934-reset-linux to doc/10934-reset-linux

#8 Updated by spriver almost 4 years ago

  • Assignee changed from spriver to sajolida

Everything is okay. I checked your changes (thanks for explaining them all, I think this should help in future work). I hope that this all isn't too much work for you as this is my first work on the original doc ;)
Is there anything else I have to do regarding this ticket?

#9 Updated by sajolida almost 4 years ago

  • Status changed from Confirmed to Resolved
  • QA Check deleted (Ready for QA)

Nothing else needs to be done on this one (maybe setting "QA Check" as "Pass", next time). So I'm merging, congrats!

#10 Updated by sajolida almost 4 years ago

  • Assignee deleted (sajolida)

Also available in: Atom PDF