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.

Comments

Perhaps the obvious question, but one to be asked.

[Mercury]

I'm a programmer, do several different languages, but I've been in the game too long, I can't view from the prospective of a user anymore, and as such can't write user interfaces nor documentation worth beans..

So my question is this, how would you suggest I learn how to write documentation which users can actually understand?

Zephaniah E. Hull.

Embedded Documentation/Extracting Docs from code

[dlc]

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!

Women, computing, Open Source

[Hard_Code]

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).

a gender thing?

[Jerom]

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.

Man pages

[Ed Avis]

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?

From the desk of a real tech supporter

[Signal 11]

I've been working tech support for going on 3 years. I've written my share of documentation, and I've read quite abit more of it. The problem with linux documentation I think is three-fold:

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?

One thing to consider

[Duke of URL]

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?

Who is the target audience?

[Seth Scali]

Okay, this seems like a basic question, but it's really kinda thorny, isn't it?

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
% ./configure (or make config, etc.)
% 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

How are you going to motivate Open Source writers?

[georgeha]

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

Translation and Localization?

[Noryungi]

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!

How to make sure that the documentation is updated

[cribeiro]

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?

Ok Deb, tell me... (longish)

[Xiphia]

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.