Comments on: How NOT to write user-friendly documentation http://blogs.gnome.org/newren/2008/03/15/how-not-to-write-newbie-friendly-documentation/ Just another GNOME Blogs weblog Sun, 12 Oct 2008 11:57:35 +0000 http://wordpress.org/?v=2.6.2 By: Nikolaus http://blogs.gnome.org/newren/2008/03/15/how-not-to-write-newbie-friendly-documentation/#comment-301 Nikolaus Tue, 08 Apr 2008 23:54:20 +0000 http://blogs.gnome.org/newren/2008/03/15/how-not-to-write-newbie-friendly-documentation/#comment-301 Terry: I think Knuth's documentation concept has a point. But this reminds me a personal anecdote: I remember that it was just that tutorial principle which drove me up the walls when I was reading Karl Marx's "Kapital". :-) He started with introducing very simple, basic ideas and claims, and it was quite obvious to me that these couldn't be true as stated. To be honest, I got angry about his flawed logic, just to find him fixing its defects and "telling the reader the truth" many, many pages later. :-) Terry: I think Knuth’s documentation concept has a point. But this reminds me a personal anecdote: I remember that it was just that tutorial principle which drove me up the walls when I was reading Karl Marx’s “Kapital”. :-) He started with introducing very simple, basic ideas and claims, and it was quite obvious to me that these couldn’t be true as stated. To be honest, I got angry about his flawed logic, just to find him fixing its defects and “telling the reader the truth” many, many pages later. :-)

]]> By: Terry Cloth http://blogs.gnome.org/newren/2008/03/15/how-not-to-write-newbie-friendly-documentation/#comment-300 Terry Cloth Sun, 06 Apr 2008 03:59:29 +0000 http://blogs.gnome.org/newren/2008/03/15/how-not-to-write-newbie-friendly-documentation/#comment-300 When trying to do documentation, it pays to remember Donald Knuth's comment: A [...] noteworthy characteristic of this manual is that it doesn't tell the truth. When certain concepts [...] are introduced informally, general rules will be stated; afterwards you will find that the rules aren't strictly true. [....] Once you understand a simple but false rule, it will not be hard to supplement that rule with its exceptions. -- D. Knuth, _The TeXbook_, pages vi--vii When trying to do documentation, it pays to remember Donald Knuth’s comment:

A [...] noteworthy characteristic of this manual is
that it doesn’t tell the truth. When certain
concepts [...] are introduced informally, general
rules will be stated; afterwards you will find that
the rules aren’t strictly true. [....] Once you
understand a simple but false rule, it will not be
hard to supplement that rule with its exceptions.

– D. Knuth, _The TeXbook_, pages vi–vii

]]> By: Kulbir Saini http://blogs.gnome.org/newren/2008/03/15/how-not-to-write-newbie-friendly-documentation/#comment-286 Kulbir Saini Wed, 26 Mar 2008 16:22:17 +0000 http://blogs.gnome.org/newren/2008/03/15/how-not-to-write-newbie-friendly-documentation/#comment-286 The link http://www.gnome.org/~newren/eg/git-for-svn-users.html is throwing 404. Can you please fix this. Would be of great help. Thanks for the wonderful work :) The link http://www.gnome.org/~newren/eg/git-for-svn-users.html is throwing 404. Can you please fix this. Would be of great help. Thanks for the wonderful work :)

]]> By: Elijah http://blogs.gnome.org/newren/2008/03/15/how-not-to-write-newbie-friendly-documentation/#comment-283 Elijah Tue, 18 Mar 2008 00:12:09 +0000 http://blogs.gnome.org/newren/2008/03/15/how-not-to-write-newbie-friendly-documentation/#comment-283 bisho: Selectively committing hunks is something you can do a couple different ways. 1) You can use 'eg commit --interactive' 2) You can stage your changes as you make them (See my in-progress http://www.gnome.org/~newren/eg/git-for-svn-users.html, in the staging changes section) and commit just the staged changes. 3) You can use 'eg add -p' (or even 'eg add --interactive') to selectively stage hunks, and then commit just the staged hunks. bisho: Selectively committing hunks is something you can do a couple different ways.
1) You can use ‘eg commit –interactive’
2) You can stage your changes as you make them (See my in-progress http://www.gnome.org/~newren/eg/git-for-svn-users.html, in the staging changes section) and commit just the staged changes.
3) You can use ‘eg add -p’ (or even ‘eg add –interactive’) to selectively stage hunks, and then commit just the staged hunks.

]]> By: bisho http://blogs.gnome.org/newren/2008/03/15/how-not-to-write-newbie-friendly-documentation/#comment-282 bisho Mon, 17 Mar 2008 15:51:55 +0000 http://blogs.gnome.org/newren/2008/03/15/how-not-to-write-newbie-friendly-documentation/#comment-282 I see... :) I was really digging in git help for this, but I was unable to find it on checkout manpage or on the tutorials. I fill stupid, hehe. Not being english native also makes things harder. When I see this on eg help I see the light: Time saving commands eg bisect Find the change that introduced a bug by binary search eg stash Save and revert local changes, or apply stashed changes One more thing: Do you know if there is something to select which changes we like to commit on one file. Some times I found two unrelated fixes and I want to commit them separately to get clear log. I usually do this by generating a diff, reseting the file, splitting the diff in two files with the different changes and applying them one, commit, second, commit. With stash I will avoid many of this problems, but it will be helpful on some circumstances. Thanks :) I see… :) I was really digging in git help for this, but I was unable to find it on checkout manpage or on the tutorials. I fill stupid, hehe. Not being english native also makes things harder.

When I see this on eg help I see the light:

Time saving commands
eg bisect Find the change that introduced a bug by binary search
eg stash Save and revert local changes, or apply stashed changes

One more thing:
Do you know if there is something to select which changes we like to commit on one file. Some times I found two unrelated fixes and I want to commit them separately to get clear log. I usually do this by generating a diff, reseting the file, splitting the diff in two files with the different changes and applying them one, commit, second, commit. With stash I will avoid many of this problems, but it will be helpful on some circumstances.

Thanks :)

]]> By: Rob Taylor http://blogs.gnome.org/newren/2008/03/15/how-not-to-write-newbie-friendly-documentation/#comment-280 Rob Taylor Mon, 17 Mar 2008 10:22:37 +0000 http://blogs.gnome.org/newren/2008/03/15/how-not-to-write-newbie-friendly-documentation/#comment-280 @bisho: in plain git, its 'git stash' ;) This is an excellent point about the discoverability of git. @elijah: Brilliant analysis of the discoverability problems of git :) EasyGit is looking great and has a cool name as well (though the contraction can get a bit confusing in a sentence, as i just discovered...). You rock! @bisho: in plain git, its ‘git stash’ ;) This is an excellent point about the discoverability of git.

@elijah: Brilliant analysis of the discoverability problems of git :) EasyGit is looking great and has a cool name as well (though the contraction can get a bit confusing in a sentence, as i just discovered…). You rock!

]]> By: bisho http://blogs.gnome.org/newren/2008/03/15/how-not-to-write-newbie-friendly-documentation/#comment-279 bisho Mon, 17 Mar 2008 09:28:29 +0000 http://blogs.gnome.org/newren/2008/03/15/how-not-to-write-newbie-friendly-documentation/#comment-279 Wohooo stash!!! I have discovered this on Easy Git after figuring quite a lot of times how to easily do it. How it's this supposed to be done with plain git??? I love the git checkout for changing between branches, but I hate that uncommited changes are brought all the way. With stash I could put them someplace while doing some fixes on a diferent branch, and later came back. Nice! Wohooo stash!!!

I have discovered this on Easy Git after figuring quite a lot of times how to easily do it. How it’s this supposed to be done with plain git???

I love the git checkout for changing between branches, but I hate that uncommited changes are brought all the way. With stash I could put them someplace while doing some fixes on a diferent branch, and later came back. Nice!

]]> By: Michael Wolf http://blogs.gnome.org/newren/2008/03/15/how-not-to-write-newbie-friendly-documentation/#comment-274 Michael Wolf Sun, 16 Mar 2008 17:29:11 +0000 http://blogs.gnome.org/newren/2008/03/15/how-not-to-write-newbie-friendly-documentation/#comment-274 All good git apologists will tell you that it all makes sense once you read a document called "git for computer scientists". And right on, I say! Until I read the Dragon Book, I was unable to invoke any command-line compilers. Until I read O'Reilly's book about pthreads, I wasn't able to use (use. I'm not talking about writing my own or anything) any multithreaded programs. Before reading Oracle's reference documentation cover to cover, I couldn't use any websites backed by SQL databases -- and not just Oracle's! Since I don't have a master's degree in mechanical engineering, I can't drive a car, and can only barely ride a bike. Without a thorough backing in finance in all its many aspects, I am incapable of withdrawing cash at an ATM. Why'd you single out git like this is beyond me. All good git apologists will tell you that it all makes sense once you read a document called “git for computer scientists”.

And right on, I say!

Until I read the Dragon Book, I was unable to invoke any command-line compilers.

Until I read O’Reilly’s book about pthreads, I wasn’t able to use (use. I’m not talking about writing my own or anything) any multithreaded programs.

Before reading Oracle’s reference documentation cover to cover, I couldn’t use any websites backed by SQL databases — and not just Oracle’s!

Since I don’t have a master’s degree in mechanical engineering, I can’t drive a car, and can only barely ride a bike.

Without a thorough backing in finance in all its many aspects, I am incapable of withdrawing cash at an ATM.

Why’d you single out git like this is beyond me.

]]> By: Rémi http://blogs.gnome.org/newren/2008/03/15/how-not-to-write-newbie-friendly-documentation/#comment-272 Rémi Sun, 16 Mar 2008 08:51:30 +0000 http://blogs.gnome.org/newren/2008/03/15/how-not-to-write-newbie-friendly-documentation/#comment-272 Great initiative anyway. I'm a big fan of git, but yeah the man pages are written in a different language than English. In comparison, even the GNU man pages make actual sense. From my experience, I've just basically learned git the "dumb" way. Try command, see if it works, if so cool, if not try different command. Lather, rinse, repeat. Anyway, I'll be trying EasyGit, but it'd be great if your idea could go back up to upstream git at some point. Great initiative anyway.

I’m a big fan of git, but yeah the man pages are written in a different language than English. In comparison, even the GNU man pages make actual sense.

From my experience, I’ve just basically learned git the “dumb” way. Try command, see if it works, if so cool, if not try different command. Lather, rinse, repeat.

Anyway, I’ll be trying EasyGit, but it’d be great if your idea could go back up to upstream git at some point.

]]> By: Janne http://blogs.gnome.org/newren/2008/03/15/how-not-to-write-newbie-friendly-documentation/#comment-271 Janne Sun, 16 Mar 2008 01:02:23 +0000 http://blogs.gnome.org/newren/2008/03/15/how-not-to-write-newbie-friendly-documentation/#comment-271 Eliah, sorry; I didn't really mean to imply that git would be incapable of being straightforward to describe. I realize my last sentence comes off that way. There are plenty of software systems (not thinking just of revision control) that really are too complex, however. No matter how good, and no matter how they simplify your life once you know them, the effort needed to learn them and teach them in the first place precludes them for use in many situations. I keep wondering, as I see people struggle with the idea of revision control, if the tools are not a bit too reflecting of the internal mechanisms. Transparency is often good, but this may be one instance where hiding the reality and present a different, more easily graspable, metaphor may be a better solution, UI wise. Eliah, sorry; I didn’t really mean to imply that git would be incapable of being straightforward to describe. I realize my last sentence comes off that way. There are plenty of software systems (not thinking just of revision control) that really are too complex, however. No matter how good, and no matter how they simplify your life once you know them, the effort needed to learn them and teach them in the first place precludes them for use in many situations.

I keep wondering, as I see people struggle with the idea of revision control, if the tools are not a bit too reflecting of the internal mechanisms. Transparency is often good, but this may be one instance where hiding the reality and present a different, more easily graspable, metaphor may be a better solution, UI wise.

]]>