Weekly Edition
Return to the Press page
| |||||||||||||
Rethinking Community Documentation (O'ReillyNet)
Andy Oram has written
a lengthy analysis of the state of community documentation
in an O'Reilly article.
"Good documentation makes good software great. Poor documentation makes great
software less useful. What is good documentation, though, and how can
communities produce it effectively? Andy Oram explores how free and open
source software projects can share their knowledge with users and how
publishers and editors fit into the future of documentation."
(Log in to post comments)
Rethinking Community Documentation (O'ReillyNet) Posted Jul 7, 2006 17:00 UTC (Fri) by allesfresser (subscriber, #216) [Link] I found his dismissal of books as "self-indulgence" on the part of the author rather ridiculous... anybody that dismisses books as being from a "bygone era" just gets a rude gesture from me, as obviously they are still useful and electronic documentation has a long way to go to equal their usefulness, especially when the power fails. :-) Also, paper has this way of preventing the Ministry of Truth effect, since it's not editable without the edits being fairly physically obvious. Wikipedia in particular fails miserably on this point.
Rethinking Community Documentation (O'ReillyNet) Posted Jul 7, 2006 17:57 UTC (Fri) by Max.Hyre (subscriber, #1054) [Link] As someone observed (and I can't find a reference...anyone know?)Hardcopy is the ultimate windowing system.There are things e-docs can do that books can't, but they can't even begin to match having three fingers at different places in a book while reading a fourth place. Until then, I'll keep my dead trees.
Rethinking Community Documentation (O'ReillyNet) Posted Jul 8, 2006 9:39 UTC (Sat) by Los__D (guest, #15263) [Link] Ehm... Bookmarks in pages beats the three fingers by... Well infinity (Or up to as much space and speed your computer has to make them, and search them)
Rethinking Community Documentation (O'ReillyNet) Posted Jul 8, 2006 9:47 UTC (Sat) by Los__D (guest, #15263) [Link] Sorry, the amount of pages would of course be the factor.
Unless the system supports bookmarks by line/word/character, then it would be much greater (And again, much, MUCH better than fingers)
Rethinking Community Documentation (O'ReillyNet) Posted Jul 10, 2006 7:53 UTC (Mon) by Wol (guest, #4433) [Link] And then your bookmark list gets huge, and you need a database to store it, and then you need to bookmark your database of bookmarks to highlight the important stuff ...
When I was studying, I was told, time and again, to only highlight the *absolute* *minimum*. Things like key WORDs, not paragraphs. Otherwise, you can't find the important amongst the "might be important".
The advantage of fingers or bits of paper in a book is that (a) you can't have that many, and (b) they're ephemeral. Those are MAJOR advantages when you're trying to highlight important information. You can't afford to waste marks on "this might be important" material.
And as someone else has said, I find working offline both easier and more productive.
Cheers,
Digital references Posted Jul 8, 2006 12:20 UTC (Sat) by Max.Hyre (subscriber, #1054) [Link] Different operating modes, I guess.I've never needed to compare more than three or four passages at one time (the upper end is mostly when reading IBM specifications), and it works much better for me to flip from one to another (or have multiple books open on the desk) than to mouse around. Of course, you're right in the longer-term case: wanting to find some passage weeks or years later. A well laid out bookmarks file can be much finer grained and easier to navigate than hundreds of pieces of paper.
Digital references Posted Jul 8, 2006 18:37 UTC (Sat) by Los__D (guest, #15263) [Link] Ahhh, true, true...
But then again, in most document readers, you can watch several pages at the same time. Works best with a wide screen display, and only two pages, though. (More is feasible if you have multimonitor, but that isn't really the normal case, especially for laptops).
Rethinking Community Documentation (O'ReillyNet) Posted Jul 13, 2006 16:33 UTC (Thu) by jhs (guest, #12429) [Link] Both have their benefits (witness those with shelves full of O'Reilly books subscribing to Safari), but for me, paper books are great.
For example, I just bought a Debian book from No Starch Press, the PDF version. I immediately had it printed and bound with a hardback-cover for around $25 US. That is less than the shipping cost to here (Thailand) and I got to choose my own cover colors and design. I chose the cover page from the PDF, so (1) I have a hardback which No Starch does not even offer (2) looks way better than the cartoonish No Starch version, which I can (3) read at my leisure, like on a train or before bed.
Hooray for hard-copy books, and hooray for No Starch's PDF-only offering!
Rethinking Community Documentation (O'ReillyNet) Posted Jul 7, 2006 18:18 UTC (Fri) by arcticwolf (guest, #8341) [Link]
That comment just goes to show what you know: nothing. Ever heard of a thing called "article history"? You actually can look up exactly who changed what at which time. Your comment makes about as much sense as M$'s past allegations that open source software is less secure because anyone can just trojan the code.
Rethinking Community Documentation (O'ReillyNet) Posted Jul 7, 2006 19:27 UTC (Fri) by egoforth (guest, #2351) [Link] A/The difference is the obviousness of the changes. When looking at a physical copy that has been altered, it is immediately ovbious to even the most naive that a change has been made. In a Wiki environment, it is, especially for the naive, certainly not immediately obvious that a change was made, or who did it. Not that that information isn't available (though I'm not a Wiki expert, so I certainly can't say what is or isn't easily obfuscated).
Rethinking Community Documentation (O'ReillyNet) Posted Jul 7, 2006 21:17 UTC (Fri) by gnb (subscriber, #5132) [Link] >You actually can look up exactly who changed what at which time.Ahem. That's true if you believe that the administrators are the good guys, otherwise you merely have the illusion that you can check the revision history. I'm not trying to cast doubt on the integrity of the current Wikipedia team, but the previous poster was correct that this is _in principle_ a problem and one that write-once media simply don't suffer from.
Rethinking Community Documentation (O'ReillyNet) Posted Jul 10, 2006 1:07 UTC (Mon) by bk (guest, #25617) [Link] Ugh. Soviet Russia got along fine using paper, as does North Korea right now. I'd take Wikipedia over the media systems of either any day.
Rethinking Community Documentation (O'ReillyNet) Posted Jul 13, 2006 16:25 UTC (Thu) by lysse (guest, #3190) [Link] The printing press - favoured tool of totalitarian dictatorships everywhere...? hmm.
|
|||||||||||||