GNOME Bugzilla – Bug 658377
Rewriting help for Disk Usage Analyzer in Mallard
Last modified: 2012-02-21 09:52:29 UTC
I will write mallard help to replace the Docbook help of Disk Usage Manager.
Thanks! feel free to ask any question here or on IRC
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.
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.
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$
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
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)?
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.
I will upload all the new topics I wrote here: http://git.gnome.org/browse/baobab/log/?h=mallard-documentation
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
> 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 :)
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$
> Merge the remote changes (e.g. 'git pull') before pushing again. That sounds like "git pull --rebase" is needed?
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!
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! :)
Ok Kat, I followed all your instructions and it worked! ^ ^
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.
Changes based on Phil comments were done.
Hi Julita, sorry for the delay... so is the new doc branch ready to be merged or still a work in progress?
Hi, Kat and I are still working on it. It could be merged in a couple of days probably.
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.
First pass (basic help, no troubleshooting) pushed to master in commits a6a9e15d0c0c7f1f76270148b77b850284663727..05a6dbea5173f9732566a6da53937dc85a91118f Closing bug, I will open a new one for remaining issues
Thanks Julita & Kat! I will release a tarball with the new help