If you're looking for a command prompt on Windows XP, I suggest Start->Run then type "cmd.exe". I recommend it over "command.com" any day.
> Download Microsoft Unix tools for Windows. You'll get a better integrated variation on cygwin
I personally use UnxUtils, it's free and the source is available. It's less invasive than cygwin, just extract the files and add that directory to your path. (I use c:\usr\local\wbin.) The typical DOS environment is still there but now you can use Unix commands to your heart's content: ls, diff, md5sum, touch, etc.
Here's a related story on Kuro5hin. I think these Glory Days may just be selective memory. Nobody wants to remember the bad stuff.
I grew up in the St. Louis area and remember listening to that station, KSHE, in the late 80s. To me, they were Jurassic rock dinosaurs who were oblivious to the exciting new music forms of the time: hip-hop, hardcore punk, and thrash. (KSHE *did* have a metal show but you had to suffer through the Jimi Hendrix and Led Zeppelin ad naseum.)
I heard better music coming out of college radio stations. I also heard KDHX, a great community radio station, when it first went on the air. It's still on the air too, so the glory days are still here!
>...I prefer the UK mags. American mags have WAY too much advertising and not nearly as much in the was of tutorials...
> a lot of the UK mags have CDs glued to them.
I agree on all counts: tutorials, CDs, and fewer ads! I enjoy Future Music (love the CD and the tutorials!) and Sound on Sound (great at explaining complex recording topics). They're too expensive to get subscriptions in the USA though.
Dr. Dobbs - trends in software development Tape Op - recording for the rest of us, although biased against digital tech
For music, I like: CMJ New Music Monthly - only for the included CD Revolver - heavy music, sometimes misogynistic though Bandoppler - for reviews of other music
I also like British magazines like Future Music and Sound On Sound. But they're too expensive for subscriptions in the USA. When I'm at the bookstore, I like to flip through Artforum and I.D.
> Linux community definitely needs more books like that
No, we don't. We need manuals that we can legally redistribute and modify (including translations and updates). So I recommend Introduction to Linux - A Hands on Guide for newbies instead.
> From the textbook: "It's not that hard to get started learning it [Tex], and we can snicker at DocBook."
Just wait until they grow more than 700 pages! The tetex package that comes with most Linux distros can't handle it. Trust me, I've hacked tetex to handle large documents.
Those of us who use DocBook reserve the right to snicker at their project... I want to point and laugh and say "I told you so." It's also humorous that their PDF lacks bookmarks.
They didn't define what they consider a programming language (Turing complete? General purpose?). Powerbuilder and m4 are general purpose languages but I didn't see them on the diagram.
If domain-specific languages are allowed, I think these were overlooked:
> Writing a book is an art - just like technical writing is. That's one reason the documentation in OSS projects is seldom at par with documentation written by professional technical/document writers.
PROVE IT! I think you've severely overestimated the quality of professionally written technical documentation. For example, why are there supplemental books for software that already comes with manuals and on-line help?
If you had said "OSS projects are seldom at par with source code written by professional programmers", you would have been flamed to a crisp. What does receiving money for something have to do with the quality of one's work anyway? Someone needs to stand up for hard-working, unpaid documentation volunteers!
> If it's done but the docs aren't, IT'S NOT DONE. > This is a philosophy that the Open Source community desperately needs to adopt from the proprietary world.
I'm a documentation volunteer and in full agreement. Eric Raymond notes in the _The Cathedral vs. The Bazaar_ that Open Source projects "release early, release often". This often generates a huge maintenance burden for the documentation volunteers.
Then he complained later about the usability of CUPS. So perhaps he should make a point to advocate "user test, document, package, and then release" instead.
Amen! I've gotten comments like "your manual could be better". Well, I can't do anything with that information... Tell me how it could be better. Be specific.
> In fact, I volunteer my time to help others in various forums and have written howtos for questions that I have seen come up regularly.
Good job!
I'm trying to encourage frustrated readers to send in bug reports. It's a leap because they've never written to a technical writer. But they probably *have* sent a "letter to the editor" to a newspaper or magazine. Hopefully, they'll write more than "your manual could be better".
> If you think that a new site full of people saying "the documentation is bad" is going to help somehow, you're delusional.
I don't blame you for being confused, there's no timeline. But I think after they gather their requirements, they'll have technical writers work on the actual documentation. No mention is made of maintenance though.
What are you doing about it? Have you sent in bug reports or re-writes?
> Finally a simple diagram of the generic file system printed in Linux Journal (that's right, even Linux for Dummies didn't bother to even show me a diagram of the file system...
Did you try The Linux Documentation Project? I found this diagram within minutes.
> Because Kernighan and Pike writing generically decades ago wrote better Linux documentation than what was available for Linux...
I assume that you're talking about _The Unix Programming Environment_. I agree that their writing on general topics is very clear and quite good. I like the style but some of the information in that book is a bit outdated now. Also, what about specific questions like how do I get my Brand X soundcard to work? or how do I sync with my PDA?
> There is a lesson here for CLI designers: make your interfaces discoverable. Tell the user how to get a list of commands and how to find out what they do.
> That is something that I would like to see - a series of documentation files consisting entirely of examples.
Go ahead. What's stopping you? I'd recommend that you don't just throw some untitled, uncommented examples together in a collection but provide some context for your readers. Answer the questions: what?, how?, and why?
BTW: I'm an Open Source documentation volunteer and I did precisely this. I added hundreds of examples to a large reference manual. Some of the users appreciated it but it was a huge maintenance burden.
Each time there was a new release of the program, I had to test each example to make sure it still worked. So the "release early, release often" mantra of Open Source development actually made my job very grueling. (Yes, I scripted the tests as much as I could.) Perhaps that's why you don't see more examples in Open Source documentation.
> The [documentation] text is jargon-rich and circular, presuming that the reader already has a knowledge base equal to that of the writer.
If every man-page and HOWTO started from first principles, the result would be voluminous (should every man-page should explain stdin, stdout, and stderr?) and redundant (readers hate reading what they already know) information. It would be a burden for both the readers and the maintainers. So documentation writers make assumptions about what their readers already know. Sometimes they assume too much...
IMHO, the solution would be a brief overview of the problem domain (like defining what an inode is) and links to more in-depth resources.
>...the help information is incomprehensible, if it exists at all.
Have you sent in bug reports for the documentation that was unclear? Have you sent in re-writes? Have you written any documentation that was previously missing?
> My career involves many publishing venues, including a very popular book publisher and a city newspaper.
When those companies publish corrections or errata, where do they come from?
>From the article: "It's here, and it's a wiki format, because that is what most of you said you thought would work the best."
How much do you want to bet "most of you" aren't active Open Source documentation volunteers? I wonder how many of those advisors volunteered to clean up duplicates, trolls, vandalism, spam, and generally off-topic rants.
Do they even read documentation off-line? Have they tried to print out a Wiki to read it later? I guess wget -r will be one of the most popular topics. LOL!
For technical documentation to be usable, it must be clear, complete, correct, and current. This requires an incredible amount of work and Wikis are no shortcut. As a matter of fact, Wiki advocates *want* unclear or incomplete entries because it encourages participation. Wikis suck for technical documentation.
> You can't really complain about newbies not reading the manual when the manual either just plain doesn't contain the information you need, or has wrong or out-of-date information in it.
Did you send in bug reports for the parts of the documentation that were incorrect, obsolete, or unclear? Most of the time, frustrated users neglect their role in improving Open Source documentation... Think of bug reports as "letters to the editor".
> radio stations such as NPR are still great sources for news
NPR lobbied againstLow Power FM radio stations. This limits competition and supports the status quo of radio consolidation (Their brother PBS network acknowledges radio consolidation as a problem, how ironic!). Just something to remember when they start one of their pledge drives.
> As Edward Tufte points out in The Visual Display of Quantitative Information, Envisioning Information, and Visual Explanations, the meaningful display of information is about removing visual clutter, not introducing it.
Since when is Edward Tufte an authority on usability?
I saw a train schedule in _The Visual Display of Quantitative Information_. To me, it was a confusing jumble of branches. I guess his point was that it was "beautiful".
I came to understand it after an hour. (I was on an Amtrak train with a superior text schedule!) My best guess was that the designers ran out of space and added branches to extend the timeline. I was confused because they looked like separate train lines.
> Isn't it time for Google finally to put some work into refining their results...
Isn't it time to also reconsider the Wiki paradigm? More sites (like this) are requiring logins. "Golden Prose" indeed! IMHO, Wikis are evolving into crude Content Management Systems.
Slashdot Mirror
> looking for a command prompt?
If you're looking for a command prompt on Windows XP, I suggest Start->Run then type "cmd.exe". I recommend it over "command.com" any day.
> Download Microsoft Unix tools for Windows. You'll get a better integrated variation on cygwin
I personally use UnxUtils, it's free and the source is available. It's less invasive than cygwin, just extract the files and add that directory to your path. (I use c:\usr\local\wbin.) The typical DOS environment is still there but now you can use Unix commands to your heart's content: ls, diff, md5sum, touch, etc.
> Glory Days? You want Glory Days?
Here's a related story on Kuro5hin. I think these Glory Days may just be selective memory. Nobody wants to remember the bad stuff.
I grew up in the St. Louis area and remember listening to that station, KSHE, in the late 80s. To me, they were Jurassic rock dinosaurs who were oblivious to the exciting new music forms of the time: hip-hop, hardcore punk, and thrash. (KSHE *did* have a metal show but you had to suffer through the Jimi Hendrix and Led Zeppelin ad naseum.)
I heard better music coming out of college radio stations. I also heard KDHX, a great community radio station, when it first went on the air. It's still on the air too, so the glory days are still here!
> ...I prefer the UK mags. American mags have WAY too much advertising and not nearly as much in the was of tutorials...
> a lot of the UK mags have CDs glued to them.
I agree on all counts: tutorials, CDs, and fewer ads! I enjoy Future Music (love the CD and the tutorials!) and Sound on Sound (great at explaining complex recording topics). They're too expensive to get subscriptions in the USA though.
Dr. Dobbs - trends in software development
Tape Op - recording for the rest of us, although biased against digital tech
For music, I like:
CMJ New Music Monthly - only for the included CD
Revolver - heavy music, sometimes misogynistic though
Bandoppler - for reviews of other music
I also like British magazines like Future Music and Sound On Sound. But they're too expensive for subscriptions in the USA. When I'm at the bookstore, I like to flip through Artforum and I.D.
Kristiansand, not Kristansand. Never heard the Tricky song?
I met a Christian in Kristiansand
I always thought it was Christiansted, part of St. Croix in the US Virgin Islands. Tricky refers to "German Jamaicans" in another song, so I thought this lyric was referring to somewhere Caribbean.
But the name of the song is Christiansands, its lyrics say that also... So it must mean somewhere else.
> Linux community definitely needs more books like that
No, we don't. We need manuals that we can legally redistribute and modify (including translations and updates). So I recommend Introduction to Linux - A Hands on Guide for newbies instead.
> If only the book was published under an open licence then I could modify it
There's always the Introduction to Linux - A Hands on Guide book. It's published under the GNU Free Documentation License. Have fun!
> From the textbook: "It's not that hard to get started learning it [Tex], and we can snicker at DocBook."
Just wait until they grow more than 700 pages! The tetex package that comes with most Linux distros can't handle it. Trust me, I've hacked tetex to handle large documents.
Those of us who use DocBook reserve the right to snicker at their project... I want to point and laugh and say "I told you so." It's also humorous that their PDF lacks bookmarks.
They didn't define what they consider a programming language (Turing complete? General purpose?). Powerbuilder and m4 are general purpose languages but I didn't see them on the diagram.
If domain-specific languages are allowed, I think these were overlooked:
BTW, you can download a more printer-friendly version here: Eric Levenez's Computer Languages History
Also, a German version is available here: German PDF
> Writing a book is an art - just like technical writing is. That's one reason the documentation in OSS projects is seldom at par with documentation written by professional technical/document writers.
PROVE IT! I think you've severely overestimated the quality of professionally written technical documentation. For example, why are there supplemental books for software that already comes with manuals and on-line help?
If you had said "OSS projects are seldom at par with source code written by professional programmers", you would have been flamed to a crisp. What does receiving money for something have to do with the quality of one's work anyway? Someone needs to stand up for hard-working, unpaid documentation volunteers!
> If it's done but the docs aren't, IT'S NOT DONE.
> This is a philosophy that the Open Source community desperately needs to adopt from the proprietary world.
I'm a documentation volunteer and in full agreement. Eric Raymond notes in the _The Cathedral vs. The Bazaar_ that Open Source projects "release early, release often". This often generates a huge maintenance burden for the documentation volunteers.
Then he complained later about the usability of CUPS. So perhaps he should make a point to advocate "user test, document, package, and then release" instead.
> Non-specific criticisms do nothing to help.
Amen! I've gotten comments like "your manual could be better". Well, I can't do anything with that information... Tell me how it could be better. Be specific.
> In fact, I volunteer my time to help others in various forums and have written howtos for questions that I have seen come up regularly.
Good job!
I'm trying to encourage frustrated readers to send in bug reports. It's a leap because they've never written to a technical writer. But they probably *have* sent a "letter to the editor" to a newspaper or magazine. Hopefully, they'll write more than "your manual could be better".
> If you think that a new site full of people saying "the documentation is bad" is going to help somehow, you're delusional.
I don't blame you for being confused, there's no timeline. But I think after they gather their requirements, they'll have technical writers work on the actual documentation. No mention is made of maintenance though.
> Finding docs is worthless if they all suck.
What are you doing about it? Have you sent in bug reports or re-writes?
> Finally a simple diagram of the generic file system printed in Linux Journal (that's right, even Linux for Dummies didn't bother to even show me a diagram of the file system...
Did you try The Linux Documentation Project? I found this diagram within minutes.
> Because Kernighan and Pike writing generically decades ago wrote better Linux documentation than what was available for Linux...
I assume that you're talking about _The Unix Programming Environment_. I agree that their writing on general topics is very clear and quite good. I like the style but some of the information in that book is a bit outdated now. Also, what about specific questions like how do I get my Brand X soundcard to work? or how do I sync with my PDA?
> There is a lesson here for CLI designers: make your interfaces discoverable. Tell the user how to get a list of commands and how to find out what they do.
Here you go:
ls /usr/bin /usr/sbin
ls
Want to find out more about program foo?
man foo
> That is something that I would like to see - a series of documentation files consisting entirely of examples.
Go ahead. What's stopping you? I'd recommend that you don't just throw some untitled, uncommented examples together in a collection but provide some context for your readers. Answer the questions: what?, how?, and why?
BTW: I'm an Open Source documentation volunteer and I did precisely this. I added hundreds of examples to a large reference manual. Some of the users appreciated it but it was a huge maintenance burden.
Each time there was a new release of the program, I had to test each example to make sure it still worked. So the "release early, release often" mantra of Open Source development actually made my job very grueling. (Yes, I scripted the tests as much as I could.) Perhaps that's why you don't see more examples in Open Source documentation.
> The [documentation] text is jargon-rich and circular, presuming that the reader already has a knowledge base equal to that of the writer.
If every man-page and HOWTO started from first principles, the result would be voluminous (should every man-page should explain stdin, stdout, and stderr?) and redundant (readers hate reading what they already know) information. It would be a burden for both the readers and the maintainers. So documentation writers make assumptions about what their readers already know. Sometimes they assume too much...
IMHO, the solution would be a brief overview of the problem domain (like defining what an inode is) and links to more in-depth resources.
> ...the help information is incomprehensible, if it exists at all.
Have you sent in bug reports for the documentation that was unclear? Have you sent in re-writes? Have you written any documentation that was previously missing?
> My career involves many publishing venues, including a very popular book publisher and a city newspaper.
When those companies publish corrections or errata, where do they come from?
> It is possible to believe strongly in both public radio and the free market
Why compete when you can just lobby away your competitors?
> Radio show producers can sign up to upload programming for peer-review
How about letting us peer-review their lobbying efforts? For now, I'm voting with my (lack of) dollars.
>From the article: "It's here, and it's a wiki format, because that is what most of you said you thought would work the best."
How much do you want to bet "most of you" aren't active Open Source documentation volunteers? I wonder how many of those advisors volunteered to clean up duplicates, trolls, vandalism, spam, and generally off-topic rants. Do they even read documentation off-line? Have they tried to print out a Wiki to read it later? I guess wget -r will be one of the most popular topics. LOL!
For technical documentation to be usable, it must be clear, complete, correct, and current. This requires an incredible amount of work and Wikis are no shortcut. As a matter of fact, Wiki advocates *want* unclear or incomplete entries because it encourages participation. Wikis suck for technical documentation.
> You can't really complain about newbies not reading the manual when the manual either just plain doesn't contain the information you need, or has wrong or out-of-date information in it.
Did you send in bug reports for the parts of the documentation that were incorrect, obsolete, or unclear? Most of the time, frustrated users neglect their role in improving Open Source documentation... Think of bug reports as "letters to the editor".
> radio stations such as NPR are still great sources for news
NPR lobbied against Low Power FM radio stations. This limits competition and supports the status quo of radio consolidation (Their brother PBS network acknowledges radio consolidation as a problem, how ironic!). Just something to remember when they start one of their pledge drives.
> As Edward Tufte points out in The Visual Display of Quantitative Information, Envisioning Information, and Visual Explanations, the meaningful display of information is about removing visual clutter, not introducing it.
Since when is Edward Tufte an authority on usability?
I saw a train schedule in _The Visual Display of Quantitative Information_. To me, it was a confusing jumble of branches. I guess his point was that it was "beautiful".
I came to understand it after an hour. (I was on an Amtrak train with a superior text schedule!) My best guess was that the designers ran out of space and added branches to extend the timeline. I was confused because they looked like separate train lines.
> Isn't it time for Google finally to put some work into refining their results...
Isn't it time to also reconsider the Wiki paradigm? More sites (like this) are requiring logins. "Golden Prose" indeed! IMHO, Wikis are evolving into crude Content Management Systems.
> It's one thing to be working with intelligent, science-oriented people. It's better to be working for intelligent, science-oriented people.
Consider the fates of companies ran by "intelligent, science-oriented people" like ArsDigita (account #1, account #2) and The MIT Blackjack Team.
> Where's the pictures? I can't read manuals without pictures.
Here's an example of a manual with pictures: Blender documentation.