After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 658377 - (jinca) Rewriting help for Disk Usage Analyzer in Mallard
(jinca)
Rewriting help for Disk Usage Analyzer in Mallard
Status: RESOLVED FIXED
Product: baobab
Classification: Core
Component: general
git master
Other Linux
: Normal major
: ---
Assigned To: Baobab Maintainers
Baobab Maintainers
Depends on:
Blocks:
 
 
Reported: 2011-09-06 17:18 UTC by Julita Inca
Modified: 2012-02-21 09:52 UTC
See Also:
GNOME target: ---
GNOME version: 3.3/3.4



Description Julita Inca 2011-09-06 17:18:06 UTC
I will write mallard help to replace the Docbook help of Disk Usage Manager.
Comment 1 Paolo Borelli 2011-09-06 17:36:15 UTC
Thanks! feel free to ask any question here or on IRC
Comment 2 Julita Inca 2011-12-18 23:54:03 UTC
Hi Paolo, when I can found you on line? UTC... I did the writing in git.gnome.org with Kat help. But it seems now the poject is called baobab and I need a little help to do again the whole thing.
Comment 3 Julita Inca 2011-12-18 23:57:44 UTC
Hi Paolo, when I can found you on line? UTC... I did the writing in
git.gnome.org/git/gnome-utils with Kat help. But it seems now the project is called baobab and I need a little help to push my whole old branch, not only new commits.
Comment 4 Julita Inca 2011-12-19 04:38:16 UTC
I got this problem:

julita@yulys:~/GNOME$ git clone ssh://jinca@git.gnome.org/git/baobab
Cloning into baobab...
Permission denied (publickey).
fatal: The remote end hung up unexpectedly
julita@yulys:~/GNOME$
Comment 5 Paolo Borelli 2011-12-19 06:42:23 UTC
Hi Julita! That's strange, cloning baobab works here:

git clone ssh://pborelli@git.gnome.org/git/baobab
Cloning into 'baobab'...
remote: Counting objects: 2261, done.
...


I should online tonight (European timezone), however I am not sure I can help a lot with that: the best thing is asking for help to the gnome sysadmins
Comment 6 André Klapper 2011-12-19 11:00:45 UTC
I get exactly this error message either when I use a wrong username, or when I do not have an SSH key available, so the obvious questions:
* Are you sure that your SSH key for git.gnome.org is in place?
* Are you sure that jinca is your Git username?
* Have you yourself successfully pushed something before to GNOME Git? 
  If so, any example (product and commit ID)?
Comment 7 Julita Inca 2011-12-19 14:07:08 UTC
Thanks for your responses, I used git before pushing in gnome-utils: http://git.gnome.org/browse/gnome-utils/log/?h=mallard-documentation

I am validating my SSH key with the administrator GNOME accounts because 
I've formatted my laptop and I generated a new key.  I hope to fix to 
start the pushing thing on my new writing in babobab. Best regards, Julita.
Comment 8 Julita Inca 2011-12-19 22:54:18 UTC
I will upload all the new topics I wrote here:
http://git.gnome.org/browse/baobab/log/?h=mallard-documentation
Comment 9 Julita Inca 2011-12-20 04:09:26 UTC
On Mon, Dec 19, 2011 at 11:08 PM, yrazes <yrazes@gmail.com> wrote:
Hi Doc GNOME Team:

I did some writings for baobab. Maybe you can read them and give me a feedback:

http://git.gnome.org/browse/baobab/log/?h=mallard-documentation

Best regards,
Julita
Comment 10 Kat 2011-12-20 10:51:30 UTC
> I did some writings for baobab. Maybe you can read them and give me a feedback:

(Remember to pull before you do any more work as I have pushed some changes!)

When you pushed changes from the previous branch that we worked on, it would have been better if you had pushed mine too. In this case they were not significant (I think I was just showing you how to write commit messages), but they could have been major and other people who work on documentation with you deserve credit for their work.

When you pushed your changes, you also included the temporary files (*.page~). These should not be pushed to git; if you used 'git commit -a' or 'git add *', you should try 'git add *.page' instead, followed by 'git commit'. Remember that you can do 'git status' to see the files that you will be committing!

The pages seem to be well formed, which is good, and the names also look sensible.

The language you use is a little too chatty, it sounds almost like you are holding a conversation with the reader; this can be more difficult for non-native speakers to understand, so try using fewer colloquialisms and making your sentences more direct.

Please use spaces for indenting, not tabs, because tabs can be displayed differently for different people. This also helps when you re-flow text to be 80 characters wide.

Make sure you always use <file> to mark up directory names.

Avoid describing where a button is or how it looks because it may be in a different place for right to left languages and a user could have a different set of icons in the style that they are using. Icons also change with time, so it's better if the help does not need to be updated when they are redone.

Use <keyseq> when the user needs to press more than one key to do something, similar to using <guiseq> when they have to click more than one GUI element.

Try suggesting to the user how they could use the results instead of telling them. For example, I would not use this application for deciding what to uninstall, so it makes my hair bristle at being told to do this ;)

I've updated introduction.page and scan-home.page to reflect the changes and improvements I suggest above. Have a look at them and see if you can apply similar changes to the other pages :)
Comment 11 Julita Inca 2011-12-20 22:30:01 UTC
Thanks Kat for the feedback, I was trying to apply all your recommendations; I did git pull --rebase, but I got this message:


julita@yulys:~/GNOME/baobab/help/C$ git commit -a
# On branch mallard-documentation
# Your branch is ahead of 'origin/master' by 5 commits.
#
nothing to commit (working directory clean)
julita@yulys:~/GNOME/baobab/help/C$ git push origin mallard-documentation 
To ssh://jinca@git.gnome.org/git/baobab
 ! [rejected]        mallard-documentation -> mallard-documentation (non-fast-forward)
error: failed to push some refs to 'ssh://jinca@git.gnome.org/git/baobab'
To prevent you from losing history, non-fast-forward updates were rejected
Merge the remote changes (e.g. 'git pull') before pushing again.  See the
'Note about fast-forwards' section of 'git push --help' for details.
julita@yulys:~/GNOME/baobab/help/C$
Comment 12 Julita Inca 2011-12-20 22:30:01 UTC
Thanks Kat for the feedback, I was trying to apply all your recommendations; I did git pull --rebase, but I got this message:


julita@yulys:~/GNOME/baobab/help/C$ git commit -a
# On branch mallard-documentation
# Your branch is ahead of 'origin/master' by 5 commits.
#
nothing to commit (working directory clean)
julita@yulys:~/GNOME/baobab/help/C$ git push origin mallard-documentation 
To ssh://jinca@git.gnome.org/git/baobab
 ! [rejected]        mallard-documentation -> mallard-documentation (non-fast-forward)
error: failed to push some refs to 'ssh://jinca@git.gnome.org/git/baobab'
To prevent you from losing history, non-fast-forward updates were rejected
Merge the remote changes (e.g. 'git pull') before pushing again.  See the
'Note about fast-forwards' section of 'git push --help' for details.
julita@yulys:~/GNOME/baobab/help/C$
Comment 13 André Klapper 2011-12-21 10:19:42 UTC
> Merge the remote changes (e.g. 'git pull') before pushing again.
That sounds like "git pull --rebase" is needed?
Comment 14 Kat 2011-12-21 12:30:30 UTC
Julita, some more feedback on the changes you pushed yesterday:

* make sure you don't have spaces at the ends of lines (I think git can remove them for you)

* reflow the text to be 80 characters wide

* "folder" is not a name or a specific folder, so should not have <file> tags around it, Home is different because it is the name of a folder

* is it really that important to order the pages inside the Preferences section in a certain way?

* the indenting looks much better now in the files which you changed ;)

Let me know when specific pages are ready for proof reading and first review!
Comment 15 Kat 2011-12-21 20:02:14 UTC
Julita, I thought some more detailed feedback for the description on introduction.page would be useful:

Originally, you had "<desc><app>Disk Usage Analyzer</app>; also referred as <app>baobab</app>, is a graphical directory tree scanner.</desc>":
* the semicolon (;) is usually used to merge two independent sentences into one, so since you were trying to insert "DUA is also referred to as baobab", a parenthetical phrase, into "DUA is a graphical directory tree scanner", commas are more appropriate
* what you are trying to say is good and appropriate for a description, although "directory tree" is not the right term to use because "folder" is more user friendly than "directory" and "tree" described the type of structure that folders are in

So, I changed it to "<desc><app>Disk Usage Analyzer</app>, also referred to as <app>baobab</app>, is a graphical file system scanner.</desc>":
* fixing the grammatical error mentioned above
* replacing "directory tree" with "file system" because the term is less specific, encompassing folders, the files inside and the structure

Which you changed to "<desc><app>Disk Usage Analyzer</app>, also referred to as <app>baobab</app>, represents graphically how much disk space folders are consuming on your hard drive.</desc>":
* "represents" is more abstract than "is", it is better to keep the description specific, simple and direct
* folders cannot "consume" something, they should also not be personified
* you do not know that the hard drive belongs to the person reading the help, so it is not a good idea to say "your" hard drive
* "disk" and "hard drive" are not correct because baobab also scans devices which are not disks and it will scan any file system which you point it at
* the description is almost twice as long here and does not add any new information, while the aim of it is to "provide a short description for a page", so it is better to keep it short

I suggest that you reset the description to be my modified version of your original one. To do this, first check that you have no staged files ('git status', and if you do, use 'git reset .' to unstage them). Next, find the commit ID for the commit where I last modified the page, for example, by looking at the log of commits ('git log'). The commit ID in this case is '85c0fbeb35a9d4d5b79f8ea9de76a196e49db12e'. Finally, reset just the one page with 'git reset *commit ID* *path to page*', which will probably look like 'git reset 85c0fbeb35a9d4d5b79f8ea9de76a196e49db12e help/C/introduction.page' and commit the change with 'git commit' (the file is automatically added when you reset it).

If you need any help or a more detailed explanation, just ask! :)
Comment 16 Julita Inca 2011-12-21 22:45:21 UTC
Ok Kat, I followed all your instructions and it worked! ^ ^
Comment 17 Julita Inca 2011-12-28 15:34:57 UTC
Phil Bull review comments:
-------------------------
introduction
 * Calling it a "graphical scanner application" is misleading, since users may confuse it with a program that operates a scanner. It might be better to directly say what Baobab can be used for, without using technical words, e.g. "checking how much disk space your files and folders take up". The second sentence in the first paragraph would make a good replacement!
 * Try to use simpler, more direct phrases. For example, "It uses charts to graphically represent your usage of hard disk space" could be written as "It uses charts to show how much disk space is being used."
 * "volume" and "mounted" are technical terms, try to avoid them.
 * (Para 3): It's not obvious why Baobab 'automatically detecting changes' is useful.
 * "the volume of each folder". "Volume" is probably not the right word for this - it's more like "the disk space taken up by each folder".

scan-file-system
 * (Para 1): Why should the user care about the usr and mnt directories? These won't mean anything to most users. You might want to say "external hard disks" instead of "mnt".
 * It's not obvious that the user should choose one of the available options in the list, rather than doing all of them.
 * "filesystem" is a technical term. Use "disk" instead.
 * The warning note should just be a normal paragraph.
 * The second note is very technical. Place this at the bottom of the page, and use the "advanced" type instead.
 * The third note should be a normal paragraph rather than a note.
 * The final note should be mentioned just after the list, since this is where the information would be of most use to the user (i.e. just after they have started the scan).
 * It would be useful to give a (very) rough indication of how long a scan should take.

scan-folder
 * Good use of examples to let the user know why this feature is useful.
 * The first paragraph should be a bit shorter.
 * "Heaviest" doesn't make sense in this context. Use "takes up the most disk space" again.
 * As above, the list of options could be confusing.
 * The comments for the notes in "scan-file-system", above, apply here too.
 
scan-home
 * "XDG user dirs" are an advanced topic. There is no need to mention that here.
 * The comments for the notes in "scan-file-system", above, apply here too.

scan-remote
 * The first sentence should be a simple one, explaining that you can use Baobab to scan folders shared over a network.
 * You should mention that scanning over a network may be slow.
 * I don't understand what the first note means. It might need more explanation, and it probably shouldn't be a note.
 * The list of protocols should help the user to choose which protocol is appropriate for their network, rather than just defining what the protocol is. For example, how can I find out which protocol I should use for my Windows network?

view-rings
 * This should probably be merged with view-tree.

view-tree
 * Mention that the size of the boxes is proportional to the amount of disk space being taken up.
 * "unities" => "units".

allocated-space
 * This is a good choice of topic to cover, since it may be a point of confusion for the user.
 * The instruction list only has one item. It should just be a normal para instead.
 * Explain what "apparent size" means, and what the difference is with "actual" usage.

tool-status-bar
 * This topic isn't needed, it's a really minor option.

no-come-up
 * The first option doesn't make sense. It should probably be 'gksudo baobab'. But using sudo can be dangerous, and it isn't used on some distros! Is this really necessary?
 * The second option will be difficult for people to follow.
 * A good first option would be to open a command line and try to run baobab from there, to see if there are any warnings that pop up on the command line.

multi-core
 * The description says "multicore", but this isn't correct. "Multicore" means that it has several CPU cores, not several hard disks.
 * The note should actually be part of the <steps> list.

virtual-folders
 * "root user" and "kernel" are technical terms. They need to be explained more.
 * "vmlinuz" has nothing to do with virtual machines.
 * The note is good, good use of link.
Comment 18 Julita Inca 2012-01-16 15:39:54 UTC
Changes based on Phil comments were done.
Comment 19 Paolo Borelli 2012-01-29 17:03:52 UTC
Hi Julita, sorry for the delay... so is the new doc branch ready to be merged or still a work in progress?
Comment 20 Julita Inca 2012-02-18 10:35:08 UTC
Hi, Kat and I are still working on it. It could be merged in a couple of days probably.
Comment 21 Kat 2012-02-18 12:04:15 UTC
Julita, some feedback on prob-no-launch.page:

* this page cannot be accessed if the application is not running
* it is too advanced
* it is too generic (same for all applications)
* no instructions on how to run Disk Usage Analyzer from the command line
* no reasoning for deleting a gconf file
* "look here" and "click here" must never be used for links
* links should point only to GNOME pages, they must not point to an Ubuntu specific page

I am going to delete this page based on the first three problems with it.
Comment 22 Kat 2012-02-21 09:35:41 UTC
First pass (basic help, no troubleshooting) pushed to master in commits 	a6a9e15d0c0c7f1f76270148b77b850284663727..05a6dbea5173f9732566a6da53937dc85a91118f

Closing bug, I will open a new one for remaining issues
Comment 23 Paolo Borelli 2012-02-21 09:52:29 UTC
Thanks Julita & Kat! I will release a tarball with the new help