Slashdot Mirror

In many instances (AFAIK) in the US, the provider is imposing artificial caps on rates, particularly upstream. The idea as I understand it is to limit the subscribers' ability to host websites and ftp servers off their DSL or cable connection. @Home was lambasted for this last year (see here for more info), especially after a configuration error at the head-end capped downstream rates!

You can find an international cable modem ISP FAQ with service comparisons here if you're looking for more information. It's dated December, 2000, so take it with a grain of salt.

-drin

That's what the OSWG is for...

Your role with the oswg seems to be akin to a secretarial/minute taker role so I am confused as to why you were asked to speak on oswg behalf. What are your qualifications? Or is this just a case of` 'look ma, isn't it cute a girl willing to post on Slashdot!'?

In this industry, documentation is all too often WORN (Write Once, Read Never). Do you feel that this attitude lessen the value of what you are doing? What are you doing to change this attitide?

As the saying goes; "Those who can, do. those who can't, teach." As the coordinator for a group of writers, wouldn't this put you on the level of a Vice-Principle?

How does it feel to be the queen of the 'Write Once Read Never' techno artefact, to be the go between between real writers and real geeks but being an expert in nothing? It must be terribly alienating.

Is it aggravated by the fact you apear to buy into the stereotype that technology is a man's world? Do you find that there is a negative backlash in this man's world because you have labeled yourself as a feminist?

From the OSWG Mission Statement:

2.5. Promoting Open-Source and Open-Content Documentation Projects
2.6. Providing an Open-Source Documentation News and Announcements Resource

It's inarguably that Linux needs a lot of good PR these days, especially when you continually see articles such as the recent one in Silicon.com. And while the public is starting to hear more positive stories about Linux, most of these are from the for-profit entities such as RedHat or VA Linux. And those are, naturally, oriented to highlight their latest endeavour or product.

How much effort does OSWG spend on press releases, seeding news stories, and offering rebuttals to erronous reports? Has the group ever been solicited for an opinion by a news agency?

The Open Source Writer's Group only has docbook. This means two divergent resources for documentation.

Linuxdoc has been officially supplanted by docbook in the community by most authoritative sources. Why hasn't the LDP started accepting docbook HOWTO's?

I don't mind writing docs, and I love being able to help out those who are looking for answers, but that fact that the most recognized resource for getting information is not staying up to date with the community is utterly frustrating.

Excuse the rant, just a frustrated docs author.

At the bottom of each index entry users are encouraged to rate and provide feedback/reviews about the document being indexed.

I hope some folks will go check the OSDI out and let me know what they think. Currently all of the OSWG and most of the LDP documents are in the index, and more are being added daily.

Open Source Writers Group

At the bottom of each index entry users are encouraged to rate and provide feedback/reviews about the document being indexed.

I hope some folks will go check the OSDI out and let me know what they think. Currently all of the OSWG and most of the LDP documents are in the index, and more are being added daily.

Open Source Writers Group

The Open Source Writers Group has some good information and resources on this topic. They held a BOF as ALS which was very informative.

In my opinion, the problem isn't documentation for newbies, its documentation for intermediate users. There is a ton of documentation aimed at the complete newbie, the home/office Windows user that has only just recently heard of Linux and decides to give it a try. Most of it is good enough. Its not perfect, but it will get most people through to the next stage.

And this is where they get lost. Fine, Linux is installed, they've got pretty little things to click on and maybe they're even on the Net. Now what? Here is where there is a lack of documentation.

For example, I don't think I've ever seen a clear set of intructions detailing how to download and install an arbitrary software package off the Net. I haven't really looked for one, I will admit, but I've never noticed anything like that over at the LDP or anything.

Also, most documentation breaks down when the user wants to do anything 'adventuresome' -- more than just word processing, emailing, and surfing the Net. Its assumed that a "Linux for Dummies" (please don't sue me IDG) book is for Dummies, and that these Dummies are unwilling to learn anything that don't need to, that reading makes their brains hurt. But what about the people that do want to learn? Where is the documentation for them? I'm not talking about the "The Linux Kernel Hackers' Guide", "Beowulf HOWTO", or other high-end specialty topics. I'm talking about wannabe geeks that want to read clear, concise, complete documentation about everything they can get their hands on. Sure, they could learn everything by experimentation, or asking questions, but wouldn't some decent docs save alot of time and anguish?

You can divide most documentation into two groups:

1. Dumbed down, simple howto instructions that give no depth to the subject. Great for absolute newbies who are unable to think on their own.

2. Exceedingly complicated, jargon-filled monstrosities on obscure technical topics that leave anyone who isn't a regular Linux hacker scratching their head.

Perhaps this is a slight overexageration. I don't think all docs suck. I find some (most?) of the LDP's HOWTOs to be decent references. I've got a couple Linux books that aren't absolutely horrible. Mailing list archives can provide startling insights.

Oh, and a point about man pages. These are obviously not geared towards the novice. Perhaps a different set of man pages would be helpful. Instead of a long listing of options, how about a longer description of the command, details on common uses, and examples of all of the options? To a newbie, that is alot more useful than set of confusing switches he'll never use.

Another thought I've just had: What about a collaborative (Open Source? heh) documentation project that can be easily updated as it is proved to be inadequate? Even something like the PHP manual where people can pose questions and have them answered. Its cool because you can post a question directly following the description of a function, and people will answer that question.

This is the lazy way to go, but it might be the best way. The other way is to have writers update the documents based on input from readers. The problem is finding people knowledgable enough to cover any given subject that have enough free time to keep the material updated.

I'm a big fan of the OSWG, even though they hate me. :) They've got some good people and some good ideas, and the work is starting to flow. They've got a few newbie guides in the works, including "Linux for Starters", "Migrating from Windows to Linux", and "Non-Condescending Guide to Linux for New Users". Unfortunately, all of these are in their 'early planning stages' and won't be available for along time.

A central resource with all of the available Linux documentation easily accessible would be nice. A searchable, linkable, browsable archive containing each and every last gem would be invaluable, methinks. Of course, it would have to be kept up to date. The OSWG is rumored to be working on something along these lines.

The real problem with getting people to write documentation is that its not 'sexy' enough. People would much rather be playing Quake, or coding some killer app then spending their time trying to write interesting documentation on something most see as a boring topic. I really don't think that documentation (or its authors!) get the attention is deserves. So here I'm going to give a great big THANK YOU to all of the worlds Linux and Open Source documentation writers and the FAQ and HOWTO maintainers. You guys provide an invaluable service. Keep up the good work.

I'd better stop on that note, before I think of something else to say.