GNOME Bugzilla – Bug 376098
seahorse's manual is not updated
Last modified: 2007-01-11 17:37:15 UTC
Documentation Section: Entire documentation The manual for seahorse is not updated to the last release. Correct version: Other information: I've worked out a initial patch for seahorse posted on the ML. I will use the bug here for next patches (or better use the ML?).
Please attach patches here so that they aren't lost on the mailing list. Thanks.
Created attachment 76998 [details] [review] First patch for the manual This is the first patch t oseahorse's manual. It's not complete at all, but: release early, release often! ;)
Created attachment 76999 [details] [review] Patch for seahorse-ssh-generate.glade This is a patch for seahorse-ssh-generate.glade. It adds a signal to the help button of the dialog for opening the manual.
Please only attach patches in the unified diff format. cvs -z3 diff -u > <patch name>
Created attachment 77032 [details] [review] resend of manual patch I'll resend the patch in unified diff. Sorry.
Created attachment 77033 [details] [review] resend of seahorse-ssh-generate patch I'll resend the patch in unified diff format.
Wonderful. Committed. I also updated the seahorse credits to include you as in the documentation credits. That said, I still think the manual needs a good deal of work. It's in no way your fault, of course.... Although progress has been made, the manual still seems too technology oriented rather than task oriented. As a new user I'd want to see topics like: * Communicating securely via email * Securely sending files to others * How to tell who an encrypted message came from. * Connecting to other machines using Secure Shell. * Stored Network Passwords etc... I don't have much experience with documentation, but I'll be working on some of this. Only because it desperately needs to be done, and it's the maintainer's job to do the dirty work... Any contributions in this direction are of course welcome.
2006-11-23 Nate Nielsen <nielsen@memberwebs.com> * src/seahorse-ssh-generate.glade: Hook up help button. Patch by milo_casagrande@yahoo.it. Fixes #376098 2006-11-23 Nate Nielsen <nielsen@memberwebs.com> * AUTHORS: * help/C/seahorse.xml: * src/seahorse-key-manager.c: Update to the user manual by milo_casagrande@yahoo.it. Fixes #376098
> That said, I still think the manual needs a good deal of work. Yes, I think so. As said on g-d-list, introduction needs a rework. I'm on SSH properties section now, but I can rework a little the intro too. I think I'm going to use this bug for next patches, should it be reopen?
Created attachment 77075 [details] [review] small patch This is a small patch: as said on the mailing list it corrects a little the introduction (smaller than before), it adds a brief description of OpenPGP on the "Creating Encryption Keys" section, a little work on the "Subkeys" section in "OpenPGP Properties" but needs some more work, I've correct the link at seahorse webpage.
Created attachment 77130 [details] [review] new patch for the manual Thi is a new patch for the manual. I've added the SSH properties, reworked a little the PGP and SSH creation and the intro. The "getting started" section needs a little more work and at least one screenshot (i'll take a look at this).
Committed, closing again. :)
Created attachment 77177 [details] [review] new patch for the manual Another small patch for the manual. I corrects a problem when trying to poen the manual from the private/public key properties dialog. Small update of the signing key section (still commented out).
Committed. Though I'm not sure about describing OpenPGP as an RFC and linking to it. Could it be described as an open implementation of public keys cryptography instead?
Created attachment 77248 [details] [review] new patch Ok! I've eliminated the RFC ref and added a brief description. ;)
Wonderful. Thanks. 2006-11-28 Nate Nielsen <nielsen@memberwebs.com> * C/seahorse.xml: Describe PGP better Patch from milo_casagrande@yahoo.it on #376685
Created attachment 77688 [details] [review] new manual patch I've worked out a little the sections, deleted the one on GConf key (moved on l.g.o), completed the "Getting Started" and added a screenshot, some work here and there.
Created attachment 77689 [details] seahorse image This is the screenshot of seahorse's main window.
Could you redo that screenshot without the drop shadow or the callout numbers please? Drop shadows can be a distraction, and callout numbers mean more work for future maintainers and translators. Also, in this case, I don't think they're really necessary -- it's safe to assume the user recognises the menu and toolbar. I'd best hold off applying your patch for now, as it would be adding a reference in the makefile to the image that isn't there yet, and I don't want to break anything :) Regard screenshots, I see a lot are in the figures/ directory, and they're all out of date. These aren't currently in use in the manual, and I don't think they are needed. (In general, it's best to use few screenshots, and maybe only one of the main window like you've done. There's more on this in the Style Guide: http://developer.gnome.org/documents/style-guide/infodesign-8.html#infodesign-10 )
Sorry, I meant "Regarding screenshots..." in the last comment, and I meant to say that I'll remove them from CVS and the Makefile.
Created attachment 77748 [details] new seahorse image The new seahorse image! ;)
Thanks :) Committed both. I've changed the table to a list, as the numbers aren't needed and it's easier to read. Could you add to it something about the 'First time options' pane that's shown in the screenshot please?
Milo, I looked over the changes in CVS HEAD and things look pretty good so far. Three things I caught were: * Creating Encryption Keys: It seems confusing that this section is entitled Creating Encryption Keys and the next section is Creating Secure Shell Keys. It should probably be Creating OpenPGP Keys * OpenPGP Key Properties:Photo IDs The description should be changed to indicate seahorse will offer resizing and converting for any image format supported by GDK. * Encryption Preferences:Server Types:HKP Servers the URL for the MIT server is correct, but the display text contains a space. Thanks for your hard work on the manual.
Created attachment 77861 [details] [review] patch for the manual This patch adds a brief description of the "First time options" pane as for the descriptions of the menubar, toolbar... I've modified the PhotoIDs section and added a little description for resizing and converting (it's really short, unfortunatley I've never used this feature so I don't know much about it :( ) Corrected the url in the HKP server and a typo.
I think (IMHO) that the manual could do it for a 1.0... I would be glad to work on it even in the future, maybe splitting it up in a couple of files for easier working and adding some more instructions (like the ones Nate pointed out some messages above). I'll ask to check it our for any kind of errors (typo, spelling) as english is not my first language! ;) Cheers!
Patch applied, thanks :) I've done a very quick bit of proofreading. One thing I've spotted is that both of the 'Creating *** Keys' sections are quite wordy. I've trimmed down a bit, but there's some things I can't fix because I don't have access to the app. Don't bother saying 'you will be prompted', just say 'choose PGP Key from the [whatever type of GUI control it is]' This bit too: 'After following the instructions above, you will be presented with a dialog to fill in.' Does the app really open two dialogs? We're still calling it a project in the Introduction. P&EK is an app, not a project. In the first sentence, say what the app does: 'Use Passwords and Encryption Keys to create and manage PGP and SSH keys.'
I have finals this week and next, but I'll try and find some time following that to carefully proof and verify the manual. Let me know when you get it in a state that you would like me to go over it with a fine tooth comb.
Created attachment 77913 [details] [review] new manual patch
(In reply to comment #26) > One thing I've spotted is that both of the 'Creating *** Keys' sections are > quite wordy. I've trimmed down a bit, but there's some things I can't fix > because I don't have access to the app. Yes, they are. But I think a little background on what the keys are ment to be is useful... > > Don't bother saying 'you will be prompted', just say 'choose PGP Key from the > [whatever type of GUI control it is]' > > This bit too: 'After following the instructions above, you will be presented > with a dialog to fill in.' Does the app really open two dialogs? I've worked out these sections in the new patch... For the opening of the dialogs: it opens the first one with the selection of the key type, closes this and then opens the one with the fields to fill. > We're still calling it a project in the Introduction. P&EK is an app, not a > project. In the first sentence, say what the app does: > 'Use Passwords and Encryption Keys to create and manage PGP and SSH keys.' Should be ok now! Cheers!
(In reply to comment #29) > (In reply to comment #26) > > One thing I've spotted is that both of the 'Creating *** Keys' sections are > > quite wordy. I've trimmed down a bit, but there's some things I can't fix > > because I don't have access to the app. > > Yes, they are. > > But I think a little background on what the keys are ment to be is useful... Yes, absolutely. What I meant was more the lengthy instructions -- eg I've cut the "either open the dialog by doing X or Y etc etc". There's no need to mention shortcuts, especially when doing so means you need a bullet list. > > This bit too: 'After following the instructions above, you will be presented > > with a dialog to fill in.' Does the app really open two dialogs? > > I've worked out these sections in the new patch... > For the opening of the dialogs: it opens the first one with the selection of > the key type, closes this and then opens the one with the fields to fill. I'm not sure that's terribly good usability. It certainly makes explaining it in the docs a little roundabout, "the dialog closes and another one opens" etc. OTOH having a a menu item for each key type might be better, but I can't say for sure as I can't get the app I'll commit this patch later today :)
(In reply to comment #30) > Yes, absolutely. > What I meant was more the lengthy instructions -- Ah, ok! My misunderstand... > eg I've cut the "either open > the dialog by doing X or Y etc etc". There's no need to mention shortcuts, > especially when doing so means you need a bullet list. Yes, should be ok now... > I'm not sure that's terribly good usability. It certainly makes explaining it > in the docs a little roundabout, "the dialog closes and another one opens" etc. Yes, definitely, explaining it that way is cumbersome... better say nothing at all :) (and I cut that part in the patch) > OTOH having a a menu item for each key type might be better, but I can't say > for sure as I can't get the app Well.. the way it works now looks good, maybe in the future there would be support for certificate too... so ... I don't know. A little more consistency between the gui elements and buttons is needed. > I'll commit this patch later today :) Thanks!
Ok. Patch committed. Some more examples of wordiness: - To create Secure Shell keys in Passwords and Encryption Keys -- no need to say 'in this app', it's implied - choose Key → Create Key Pair from the menubar -- no need to say 'from the menubar', it's implied - 4.1. Fields description -- no need for a heading. That sort of heading seems wrong anyway: it's at once too complex and too vague. - 'The advanced options fields are detailed below.' -- if possible, avoid this sort of exposition. There's more of it elsewhere in the manual, eg 'After following the instructions above, you will be presented with a dialog to fill in.' I've made some changes -- it's actually turned into quite a rewrite of that section... :) Here's how it works: - quick numbered instructions that give all the steps in one chunk that's easy to follow - the stuff on actually creating is brought above the advanced bits (daft title anyway, since the whole page is about creating a key) - the advanced stuff that nobody's going to read is kept in its own section. Easier to follow and less cluttered, I think. When you say 'Choose <guilabel>Secure Shell Key</guilabel>', what sort of dialog box control is this? If it's radio buttons, should be 'select' for example. I would seriously consider filing a bug for splitting the Create New menu item. Now you have the entire procedure laid out cleanly, it involves FIVE steps, and THREE dialogs. That's a lot. A specific "Create SSH Key" menu item cuts that down to four and two.
Created attachment 77970 [details] [review] a new patch
(In reply to comment #32) > I've made some changes -- it's actually turned into quite a rewrite of that > section... :) > > Here's how it works: > > - quick numbered instructions that give all the steps in one chunk that's easy > to follow > - the stuff on actually creating is brought above the advanced bits (daft title > anyway, since the whole page is about creating a key) > - the advanced stuff that nobody's going to read is kept in its own section. > > Easier to follow and less cluttered, I think. I've reworked the OpenPGP creation as for the SSH key... looks better now! Thakns for the tip! ;)+ > When you say 'Choose <guilabel>Secure Shell Key</guilabel>', what sort of > dialog box control is this? If it's radio buttons, should be 'select' for > example. Actually is a dialog with a GTkTreeView inside... > I would seriously consider filing a bug for splitting the Create New menu item. > Now you have the entire procedure laid out cleanly, it involves FIVE steps, and > THREE dialogs. That's a lot. A specific "Create SSH Key" menu item cuts that > down to four and two. Yes, sounds better. Cheers.
That was fast! Committed.
BTW, Milo and Joachim, thanks for all your hard work on the docs. You guys rock!
Created attachment 78395 [details] [review] small patch This patch resolves two little errors in the manual: - a "dialog" missing - the button for just creating a SSH key "Just Create Key" was mentioned as "Create"
Thanks :) Committed.
Created attachment 78885 [details] [review] new patch for the manual This is a christmas-patch! I've reworked the last three sections of the manual: - "File Manager" - "Text Editor" - "Encryption Preferences" that now is a more general "Preferences". Bye!
Thanks for the patch! Committed.
I proofed the previous version and committed some minor changes.
Closing this bug as all patches have been applied. Thanks Milo for all of your hard work!