Merge lp:~clissold345/ubuntu-docs/revision-of-volumes-and-partitions-page into lp:~ubuntu-core-doc/ubuntu-docs/trunk2017-07-10

Here's a new revision 592. It's got everything from the old revision 592 in it, plus I made a correction to the desc field in disk-partitions.page, plus I changed disk-capacity.page (as discussed by email with Doug yesterday).

Regarding disk-capacity.page: could we give the user some indication of what "too full" means? Over 90% full they should consider taking action?

Thinking... Three methods to do approximately the same thing. Doesn't that give our desktop guide a bias towards disk analyzing?

They are all GNOME tools, they are all installed on Ubuntu by default, and the current wording of disk-capacity.page is similar to the GNOME equivalent:

https://help.gnome.org/users/gnome-help/stable/disk-capacity.html.en

Before adding this third way, I think it would be a good idea to ask some GNOME person if it's just a coincidence that Disks isn't mentioned on that page. Jeremy Bicha, who is deeply involved in Ubuntu GNOME, might be able to shed some light on it.

For my part of it (from the e-mail thread), I thought the existing two methods looked the easiest, which is why I suggested the addition be listed third.

I'll have a think about disk-capacity.page and probably make some suggestions about how to improve it. (I don't think it's a very good page - but I wasn't greatly concerned to improve it, I mainly just wanted Disks mentioned.)

Maybe there is a preferred way, given the GNOME plans, in which case we should focus on that one. That's one thing which Jeremy might know. (An easy way to involve him would we to subscribe him to your branch.)

Well I've subscribed Jeremy to the branch. I hope I've done it right.

Hi Jeremy, do you have a view on how to revise disk-capacity.html? The current released version is here:

https://help.ubuntu.com/stable/ubuntu-help/disk-capacity.html

I'll post another comment about this shortly (in about ten minutes).

I'd like to rewrite disk-capacity.html as one procedure (and I think it would be a short procedure). This would mean that the page was similar in style to many of the other task-orientated pages in the desktop help.

If the task of the page is to check disk usage and if necessary free up space, then the procedure would be something like this: Open application XXX (I prefer Disks myself but I don't think it greatly matters which application the user uses to check disk usage) from the Dash and check disk usage, if the disk is "too full" (what does that mean?), free up space by either deleting files that you don't need any more or backing up important files and deleting them.

The procedure can be applied to any disk/volume not just a volume on a hard drive, so I think it's worth generalizing the procedure slightly to make that clear.

I don't really work on the Docs teams these days so these are just my opinions and not a formal review.

I'm not aware of plans to drop the Disks or Disk Usage Analyzer apps from the default GNOME install (although that could be done by distros if they wanted).

My opinion is that pages like this that are clearly nearly the same behavior as GNOME should be kept in near-sync with GNOME. (Replace "Open the Activities Overview" with "Open the Dash", etc.).

So, my recommendation is to submit a tweaked version of this change to the GNOME Docs team.

Other suggestions:
- Try to keep the line length short. There's not a formal 80-character line limit like some projects but the lines you add or change shouldn't be much longer than other lines.
- Use the Unicode single-character ellipsis (…) rather than three separate characters (...)
- While I liked the idea of using the same page for both Unity and GNOME with the if: conditional and submitted a bunch of that to GNOME, my changes were reverted there. I think it was because it added extra work (and some confusion) for GNOME translators and made the pages more difficult to read for those working with the Mallard source. Also, the if: conditional didn't work for page titles or for images I believe. Therefore, there still would need to be 2 Ubuntu packages: one for GNOME and one for Unity.
- I don't think a merge from gnome-user-docs has been done since I last did it a few years ago. I strongly recommend using the Meld app if someone wants to work on that large project.

Jeremy wrote:

> - I don't think a merge from gnome-user-docs has been done since I last did it a few years ago.

There has been one since, led by Kevin Godby, although a lot of us helped.

Hi guys, I take note of some of the things that Jeremy wrote (eg if I change disk-capacity.page (and it's approved) I'm fine to email the new page to the Gnome help team so they can use it if they want to).

However, I can't see that a general discussion of Gnome help/Ubuntu help affects my opinion of disk-capacity.page. The change I'm proposing seems to me an obvious (minor) improvement to the Ubuntu help. I'll do a draft (rather than again describing what I want to do). Hopefully it will then be clear that it's a minor change. Note: I'm not assuming the draft will be approved. If anyone can give strong reasons against it, I'll throw it away.

I like the idea to make the page more task-orientated. If you change it in that direction, you'll address my concerns above.

Here's another revision 592. I hope you weren't expecting the changes to disk-capacity.page to be very exciting!

I've written the instructions a bit more generally than before. Eg a disk may have more than one data volume on it.

I've sometimes written "disk/volume" as an attempt to remind the user that strictly speaking we're not talking about disks, we're talking about volumes.

I think the list in "What if the disk is too full?" should be a bulleted list since it's not a procedure (= steps that have to be done sequentially).

I'm thinking of adding a brief mention of Disk Usage Analyzer in "What if the disk is too full?" since it can help the user find the big files.

I'm away until Monday so I won't be doing any more drafts until then.

Ok, thanks Chris.

I must admit that I have almost no own experience of using any of the tools in question. But if I understand it correctly, both Disks and System Monitor can be used to display utilization at a high level, i.e. per partition. It's similar to the df terminal command, if I understand it correctly. Now you picked Disks over System Monitor, and that's fine with me.

Disk Usage Analyzer seems to be quite different. It allows you to pick either a whole partition or part of it and browse the disk usage per folder. Seems to be more like the du terminal command.

So yes, I think that a brief mention of Disk Usage Analyzer is motivated. Maybe something along:

"Disk Usage Analyzer, which allows you to view disk usage per folder, can be used for a more low level examination."

and then include the link to help:baobab. (I'm sure it can be better worded.)

With such an addition I think we achieve an improvement.

Hi Gunnar, thanks for taking the time to review this.

I've kept the mention of Disk Usage Analyzer very brief because using Disk Usage Analyzer isn't essential to the task in hand (but it could be useful).

Terminology: "back up" is the verb and "backup" is the noun.

I think the new page will be a significant improvement on the old page (though I'm not claiming it's a revolutionary improvement).

Looks good now.

Thanks!