Slashdot Mirror
Ask Deb Richardson About Open Source Documentation
Deb Richardson is the force behind the Open Source Writers Group. Plenty of people complain about poorly written, poorly indexed Linux, *BSD, and Open Source documentation. Deb is one of the few actually doing something to make things better. Want to help? Ask her how. If you're a developer, ask Deb how you can write better docs -- and how you can tap into the growing pool of volunteer writers and editors she has put together. Or ask her anything else - go ahead and post your questions below. Deb's answers are scheduled to appear Friday.
I am not an OS programmer, just a user. In my experience, the documentation provided with the *BSDs is excellent. Granted, individual programs sometimes have lacking documentaion, but for a fresh install OpenBSD has the best system documentation IMHO. I know it is up to both the operating system programmers _and_ application programmers to both write good docs, but if a new-user cannot find ample documentation _locally_ on thier system and about thier system, it leaves a sour taste. All the apps you have can have excelent documentation, but if you are struggling to figure out the layout of
I'm looking at a fresh install of RedHat 6.1 and Slack 7.0 right now...and I have rather sparse system info in
My question is this: How hard would it be to re-document an entire OS (ie - Linux)? In the long run, it doesn't matter how well documented FooBar 1.0 is. If the user can't grok the underlying OS, it's pointless.
Thank you.
There are often times where it is necessary to make criticism of either GNU/Linux or a competing system when advocating OpenSource, but merely stating one's opinion seems to draw flame from whomever is being criticized. What is the best way to "soften the blow" without losing the intendent meaning or impact of a criticism?
--
: remove whitespace to e-mail me
We may not imagine how our lives could be more frustrating and complex—but Congress can. – Cullen Hightower
Do you think that unification of format, centralization of availability, or improvement in quality are the real issues here? How can we best address these issues?
What are the rules of thumb for writing documentation?
How often do you see them followed?
What are the common mistakes committed when writing documentation?
--
then it comes to be that the soothing light at the end of your tunnel is just a freight train coming your way
There's also the HOWTOs and MINI-HOWTOs - many of which come with the distros, and they can be easily located on the web. Oftentimes these are pretty good at handholding until you get brave enough to man smb.conf or something else fairly large...
"It's tough to be bilingual when you get hit in the head."
Funny thing is, the department I worked int eh second summer had both men and women, of different races and everything; the engineering group was mostly male and mostly Indian (like me).
Was my experience typical? What's a good work environment for tech-writing-for-money? I enjoyed it that first summer, and I'd like to see why you think that might be.
Ceterum censeo Microsoftam esse delendam.
For those interested in a little more bacground on the interviewee, here's her page on linuxchix (the link on oswg.org is wrong)
http://www.linuxchix.org/docs/chix/deb. html
Ale
The Open Content web site contains a brief article that discusses one of the problems faced by open source documentation that is not faced by open source software. There are barriers to collaboration in writing that are not present in coding. Corrections of typos and updating command syntax is one thing, but there are issues of style for which there is no single right answer. So my question is, have you found any ways to increase the level of collaboration in order to lift the burden of completing each large documentation project from the shoulders of a single writer?
The net will not be what we demand, but what we make it. Build it well.
From the OSWG Mission Statement:
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?
Any sufficiently advanced civilization is indistinguishable from Gods.
Preamble: In the olden days, software came with manuals, and the software designers expected you to read at least a bit of the manuals before attempting to use the software. These days, (enlightened) developers design software to be used without manuals - in fact it is common for even commerical software to ship with nothing in the way of usable print documentation. The difference is usually made up in online documentation. Whether that's good or bad is another issue - but it does bring me to my question:
As online documentation becomes more and more important, searching online documentation becomes one of the most important functions a program can offer. In the Windows world, this started as nothing more than a grep through the documentation files. Recently, however, as things such as information retreival (IR) and natural language queries (NLQ) become hot research topics (in part due to searching the WWW), Microsoft has been at the forefront of making these technologies work. Say what you want about the Office Assistant, with each new release, it's able to better understand questions you ask it. My question is: is there any effort to bring IR or NLQ technologies to the Open Source world? Has anyone been talking to researchers at universities if they would be willing to release their source for inclusion into an Open Source project?
Complementing the above question. When a new software version is released, people that install it report bugs to the development team. However, everyone already knows the software, so they dont check if the documentation is updated accordingly. So here is the question: Do you think that we should test documentation, in the same sense that we test software? In this regard, what would be the motivation for experts to review the documentation?
I'm offering this up as an example of an open-source project which has achieved documentation!
Let me give an example of an open-source project which has fairly good documetation. The R language has documentation which you can check out on the web here I think that good doc's means run-able examples, reasonably organized information, with cross-referencing, and source code. The R language has that, mostly. Its documentation makes linux doc's look pretty shabby. I think that one reason for this is that most of the contributions are by Ph.D. statisticians, who are accustomed to technical writing. Another reason is that documentation is a standard part of an R package: if you want to make a contribution, you document it.
Hope this helps.
See what I've been reading.
1. Will there be an accepted format for documentation for all distros?
2. Who would be the overall "manual assembler"? I am assuming that your job is the thankless administration and coordination of the overall doc project. If pieces of documentation for one distro also applies to another distro, would it be rewritten or would someone be charged with the task of applying it to other documents?
3. What will be the accepted distribution medium for all the open source documents? HTML, Text, Adobe Acrobat? All of them?
4. When writing technical manuals through your organization, what are the requirements for cohesive writing? What is the accepted stylebook? Is personal style accepted, or only straight technical (de-humanized, if you will) writing wanted? If personal style is acceptable, how does your manual assembler combine differing and clashing personal styles within one document without de-humanizing it?
Thanks...
"First things first, but not necessarily in that order."
"First things first, but not necessarily in that order."
- Doctor Who
So my question is this, how would you suggest I learn how to write documentation which users can actually understand?
Zephaniah E. Hull.
As a Perl programmer, I am very impressed by the POD (plain old documentation) system that is almost universal to Perl modules and scripts -- embedding documentation into the code, with a corresponding tool to extract it. I also think that Javadoc is pretty cool -- it actually pulls out function and variable declarations and creates hyperlinked documentation based on that. Given that software documentation tends to lag behind the software itself, do you that there is a future in software that generates documentation from source code, in a more general way? Something like a set of scripts written in Perl (for example, due to it's excellent pattern matching) that would read your C/Lisp/C++/Java/Perl/Python/Pascal/whatever and generate documentation (perhaps XML in a standard format that can then be run through a 2man or 2info or 2pod).
More importantly, perhaps, do you think there is any reason to develop a XML dialect specifically for documentation?
darren
Cthulhu for President!
(darren)
Being a women in the male "dominated" field of computing, do you have any comments on the omnipresent issue of women in technology? Why are there so few. How can it be remedied, if it needs to be. Is Open Source a relevant phenomenon in providing "entry points" for women into the community. What about your impressions of the male-oriented gaming industry? [How] Do you think females can bring a different perspective to computing (lots of coding is just hack and slash, while there are greater issues of elegant design and architecture).
It's 10 PM. Do you know if you're un-American?
Open source documentation has always been
a bit of an outsider within the open-source
movement. It's also quite rare to see women
in charge of an open source project.
Do you think these two facts are somehow related?
How do you think a larger part of the female
population could be involved in open-source
projects?
J.
What is your opinion on man pages? Are they an obsolete distraction, or are they still essential for any well-documented program?
Do you think it's reasonable to use man pages for learning, or should they be written only as a reference manual?
-- Ed Avis ed@membled.com
Diverse environment.
It's very difficult to write short, concise, documentation when you need to do a writeup for over a dozen possible environments. Take setting up an internet connection on RH6. You could do it in any of the following fashions: pppd, linuxconf (ifup/ifdown), kppp, gnome's modem, etc. Each program does the same thing but has a substantially different interface.
Limited experience.
Let's face it, most people hacking code haven't done tech support long enough to aquire good writing skills. Their code is beautiful, but their explanations are severely lacking. Learning how to take the knowledge you have and lay it out to someone who knows nothing about it is very, very difficult in any technical profession.
Different userbase.
Until now, the linux community consisted mainly of highly-trained network and systems people, programmers, and well-learned geeks. Now that the balance is shifting to people who are relatively inexperienced, a huge gaping chasm for documentation has opened up.
Sorry for the length, but it was necessary to get to the question. My question is this: What can be done through an online forum to teach [experienced] people on how to convey their knowledge in a format useful to a new linux user?
When we tell new people to RTFM is sometimes they get overwhelmed. They often don't want all the extra stuff a man page has. The newbies may just want to get a step by step direction sheet of how to do things, which is fine. They learn fast that way - but eventually they're going to learn need the details.
So how do we write docs which help newbies and still give the 'learned' the details they need?
Okay, this seems like a basic question, but it's really kinda thorny, isn't it?
./configure (or make config, etc.)
On one hand, there's me:
If I want to install FooWidget 2.6, I know that I can do the following:
% ftp ftp.foowidget.org
> get foowidget-2.6.tar.gz
> quit
% tar -zxf foowidget-2.6.tar.gz
% cd foowidget
%
% make
% make install
So a doc that says: "FTP the file from ftp.foowidget.org, untar it, run configure, run make and make install" doesn't do me a whole bloody lot of good. If I'm looking at the doc, it's usually because there's a problem (i.e., it won't compile or run right).
So for me, the ideal doc is actually kinda technical-- maybe a troubleshooting guide, or a list of known bugs and workarounds.
But then there's my mother:
"What the hell is FooWidget, and why the fuck do you want me to install it?" (Yes, that would likely be her-- she's been known to make sailors blush).
For her, the step-by-step instructions are all she needs (she already knows how to troubleshoot-- she picks up the phone and calls me at work). So the ideal docs for her are the ones that will hold your hand.
So for whom do we write our docs? My mom (in which case, I will feel insulted that you think I need to be taught how to su root) or me (in which case my mother tells me that this Linux bullshit is too hard, and she wants me to re-install Windows)? Is there a compromise between the two (like with the LyX documentation, perhaps?)?
----
I have come to a conclusion about life... I am more
mentally stable than any of these activists or
Deb,
Let me qualify the following statement with my experience, I am a published writer on Open Source material. I cowrote a book on Samba for a few reasons.
1) Kicks, just to see if I could write a book.
2) Money
3) Fame, feedback, geek cred
4) To gain knowledge on Samba and networking.
Writing the book took a lot of my free time for a third of a year. The money was nice, but not especially lucrative. I've had little feedback on this book. I do understand Samba fairly well at this point.
If I understand the Open Source philosophy for programmers, you write code because you need something done. Once it's done, you share the code since it costs little to share it, gain a reputation as a good coder, and possibly parlay that into stock options or a career as a programmer.
The way I understand the Open Source philosophy for writers, you write something about something you know, you spend many hours cleaning it up to make it easy to understand, then you share it. I get little feedback, and I might get a job offer as a technical writer for far less than I'm making in my day job as a technical support person.
To me, it seems that if you want to make it in Open Source, be a programmer, not a writer.
How are you planning to give more cachet to Open Source writers, how are you planning to make it more desirable to make people spend countless hours writing Open Source?
George
As a professional translator and localization specialist, I think I have a fair idea of the challenges involved in producing good technical documents.
My questions are the following: do you think most Open Source Technical Writers or Open Source Programmers produce documents that are easy to translate or do you think this side of documentation could use some improvement?
What are the general rules you apply when considering a new documentation? Possible number of users? Importance of the project? For instance: GNOME may have more users but a program such as SendMail may well be even more important in terms of use.
I suppose you consider translation important to Open Source projects... but do you have a lot of translators that volunteer for that thankless task? And what would you advise me to do in order to have enough time to have a regular job and do my part to bring Open Source to as many people as possible?
Thanks in advance!
The right to offend is far more important than the right not to be offended. (Rowan Atkinson)
One of the hard parts of the documentation process is keeping the docs in sync with the software. People tend to fix bugs and forget to update the docs. Telling developers to maintain it does not work for several reasons. The same problem applies for tutorials and things like that. What do you think could be made to make sure that all documents are kept updated?
Firstly Deb, I have nothing but respect for your technical ability and your work with the OSWG. What I want to know is, how does a savvy professional and self-titled feminist like yourself justify your work on LinuxChix? Let me explain...
When I first discovered the LinuxChix site I was very excited... here was an opportunity to meet some of the other ladies in the industry, compare stories, and talk tech. I was sorely disappointed though... after a few weeks of monitoring the lists, I saw little technical discussion that wasn't already covered by mainstream FAQs and discussion groups, a lot of talk about boyfriends, and a fair amount of male-bashing radical talk about the need for things like women-only seminars and distributions.
Now I'm a woman in the industry, and I strongly feel that the day I can't hold my own with the big boys I should turn in my engineering ring. What's the deal? Do women need these special services because we can't handle the REAL distributions and seminars? I think not, and if a man said that (and I don't know any who would - in my experience most are EAGER to let the ladies play too) you'd smack him so hard his head would spin!
Now I believe I understand (and support) your original intent in founding the group, but on reflection I am wondering if perhaps in creating a ladies-only (or at least ladies-primarily) environment you have done the ladies a disservice. Why encourage women to cut out the majority of the knowledge base by submitting questions to LinuxChix instead of either finding their own answers online or querying the more mainstream lists?
Does LinuxChix as it exists today meets its original goals or your original vision in founding it? If so, how can you prevent it from becoming a crutch for those ladies unwilling (or unable) to deal with the real world? I hope you don't feel this is a slam... as I said, I respect you both personally and professionally, but this question has been bugging me for some time, and I had to get it off my chest. I look forward to your response.
Those who will not reason, are bigots, those who cannot, are fools, and those who dare not, are slaves. - Lord Byron