Slashdot Mirror
Deb Richardson Answers Open Source Doc Questions
One thing to consider
by Duke of URL
When we tell new people to RTFM 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 need to learn the details.
So how do we write docs which help newbies and still give the 'learned' the details they need?
Deb:
Currently there is no way to create documentation that changes dynamically according to the level and needs of the user. I think we have the technology to begin working towards these sorts of systems, but it will be a while before they're a realistic option.
Writing documentation that is targeted towards a specific audience is very important, of course. As you said, new users have different needs than experienced users. At the moment, the only really effective way to address both these types of user is simply to create both types of documentation.
Trying to address all possible audiences within the scope of a single document is simply a recipe for disaster. You will end up with either a gargantuan piece of work that takes too long to create and maintain, or you will end up with a document that tries to serve the "average user" that won't meet anyone's needs at all. Either way, you end up with ineffective docs.
Short answer: Different docs for different audiences.
How to make sure that the documentation is updated
by 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?
Deb:
Having dedicated documentation people within your project is definitely a step in the right direction. The GNOME project, for example, has the GNOME Documentation Project. Also, having your documentation people tightly integrated with the rest of the development team is very important. If your documentation people find out about changes, updates, and additions at the same time the developers do, then chances are much better that these changes will be reflected in your documentation in a timely manner.
It's also important to keep in mind that it takes time to produce good documentation. It has to be written, edited, verified on a technical level, re-edited, proofread, and so on. If you want to ensure that your documentation is in sync with your software releases then you might have to hold off on releasing the software until you know that your documentation is complete.
Documentation should be viewed as an important part of the whole product. If the documentation isn't done, then the product isn't done. If a product isn't done, then it isn't released. So, if you look at it from that perspective, it's not so much "holding back on a release" as "not releasing until the product is complete".
Will the open source community adopt this sort of attitude towards documentation? Hopefully. This doesn't go against the "release early, release often" philosophy either. "Publish early, publish often" is a perfectly reasonable way to treat documentation releases, as well.
So, I guess my answer is: get at least one or two dedicated documentation people for your project. Make sure that these people are kept completely up to date on the development process. And give these people the time they need to get the documentation "in sync" before doing your next release. Don't make your documentation people constantly play "catch up" -- this is extremely frustrating, and is a pretty quick way to discourage your volunteers. Treat them as an important and integral part of your team. The more tightly integrated they are, the easier it is to maintain up-to-date documentation.
a gender thing?
by 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?
Deb:
Do I think these facts are related? No. There are lots of open-source documentation projects out there that were founded and are maintained by men.
I think a larger part of the female population could get involved with open source projects if, ta dah, they just got involved. Yes, there are probably reasons why there aren't more women involved in open source, ranging from fundamental societal factors concerning our educational systems to the random locker-room chatter that plagues so many online forums. What are the actual reasons? I have no idea. I'm really not the right person to ask, because, well, I am involved in open source. :)
Sorry I can't help.
Translation and Localization?
by 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?
Deb:
Answer to this bit:
I've never actually done any translation, so I'm hardly an authority on the subject. I suspect that yes, this side of the documentation could use some improvement -- I've been criticized for using various colloquialisms and such in my documentation that really don't translate well, or that are hard to understand if you speak English as a second language. I've also been warned that using puns is a "no no", and that spelling counts. A translator may not recognize an incorrectly spelled word, making it remarkably difficult to translate.
A lot of the free documentation that is currently available breaks one or more of these rules, so it's pretty obvious that they could use some improvement towards simplifying translation tasks.
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.
Deb:
Personally? I pick my volunteer projects the same way most open source coders pick their projects:
1. Does it scratch a personal itch? I am more likely to write documentation for something if I have a really hard time figuring out how to use it and/or I think the existing documentation is weak. Writing documentation for a piece of software is a very effective way to learn how to use it. I also like to think that I'm saving someone else from having to go through the same problems later on.
2. Is it interesting? I'm unlikely to volunteer for something I don't enjoy. That's just a little nuts. If it bores me, I'm not going to spend a bunch of my free time working on it.
3. Is it needed? Writing docs that aren't needed is a waste of time. On the other hand, writing a document that fills a fairly significant gap and that helps a lot of people is an incredibly satisfying accomplishment.
4. Is it fun? For me "fun" and "interesting" tend to be more or less interchangeable, but sometimes boring stuff can be fun too, particularly if it means you get to work with a bunch of neat people. There are lots of uninteresting tasks that can still be fun if you've got the right people to work with.
Generally, if I can answer "yes" to at least two of these four questions, I'd probably work on the project. Or at least consider working on the project. There are a number of projects (Mozilla!) that I would really like to work on. Unfortunately, I just can't take on any more work at the moment.
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?
Deb:
Translation is absolutely important to Open Source projects. In my opinion, documentation that is only available in English is incomplete. The open source user base is, obviously, multinational, and if we're only providing for one part of that user base, then we're only doing part of the job.
Certainly the "translators" are the smallest group of volunteers we have at the OSWG, and we could always use more. So, no, we don't currently have "a lot" of volunteer translators, unfortunately :)
What should you do in order to do open source work while also holding down a regular job? That's a hard question. I think that the best thing for you to do is to find an open source project about which you are really passionate. Working on open source stuff requires a lot of time, dedication, and hard work. Trust me, after running two projects for over a year, I know. But, if you're really passionate about what you're working on, it doesn't matter how hard or time consuming it is -- you will somehow find the time. (Sadly, "giving up sleep" is often the first result :)
I'm sure that there are a lot of people who would love to contribute to Open Source but who really just can't make time. That's okay. There are ways that people can help without having to invest a huge amount of time -- send bug reports, become a Free Software advocate, donate to some of the Open Source projects that are working on stuff you really like, etc.
If nothing else, take the time to occassionally send an appreciative note to someone who has done something you think is really good -- there's nothing quite as satisfying as getting an email from a total stranger who just says "thanks, I think you're doing a good job". Really. It might seem silly, but there are some days where I have received so much flame mail, or something has gone so stunningly wrong in my project, that I've just wanted to throw in the towel and give it up completely. But getting random notes of appreciation does _a lot_ to offset that. Knowing that there are at least a few people out there who care about what you're doing can really make a difference on those darker days.
From the desk of a real tech supporter
by Signal 11
I've been working tech support for going on three years. I've written my share of documentation, and I've read quite a bit more of it. The problem with linux documentation I think is three-fold:
1) 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.
2) 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.
3) 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?
Deb:
Well, I don't know right now, but we're about to find out. The Open Source Writers Group is in the process of planning a series of "writer's workshops" that will be held via IRC and mailing lists. If you're interested, we're currently discussing the idea on the oswg-discuss mailing list...you can get information about subscribing here: http://www.oswg.org:8080/oswg/list_info
Perhaps the obvious question, but one to be asked.
by 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?
Deb:
Well...the short answer is "this is why tech writers exist in the first place". Writing good user documentation is challenging for this very reason. That's not really a great answer tho' :)
How can you learn how to do write docs? There are a lot of books out there about technical writing -- do a search for "technical writing" on fatbrain.com, and it returns 203 titles (I have no idea how many of these are actually about tech writing, but the first page of results contained a large number of relevant titles). Go poke around the bookstore and see what you can find.
There's also the "practice makes perfect" school of thought. Write some docs, give them to some people to test and get their comments back. Do some rewriting and editing in light of these comments, then do it again. And again. This can be a pretty time consuming process, of course, but it is a basic form of "usability testing". Usability testing should be done on docs as well as software, and usability flaws should be treated like bugs.
After a few iterations of this, you will probably have some pretty solid docs to release. Make them available to the community ("publish early, publish often") with a note encouraging reader comments and suggestions so you can continue to get more feedback for future revisions and improvements.
Just remember that writing good documentation is actually really hard. Don't get too frustrated if your first few attempts are pretty sucky. Mine were, but that certainly hasn't stopped me yet ;)
How are you going to motivate Open Source writers?
by georgeha
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?
Deb:
Hm. Well, this is a really good question. I don't know. I've been thinking about how to make writing free docs as "sexy" as writing free code for quite a while now, and I haven't come up with anything yet. As I keep saying, writing docs is hard work. If anyone has any ideas about how we could get more people working on docs, I'd love to hear them.
Right now, writing free docs is a labour of love. Unfortunately, there aren't nearly enough of us who love this stuff. We really need more and better free documentation.
Man pages
by 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?
Deb:
I think man pages, or some man-page-like facility, is extremely valuable. Having an instant reference available is always a good thing.
Are man pages a good learning tool? Not really. For example, do a `man tar' right now. Go ahead, I'll wait. [pause] As you can see, the current tar man page is awful. If I were a new Linux user and got that when I was trying to learn how to use tar, I'd have no idea where to begin. All I need to do is `tar -xvzf filename.tar.gz', but trying to figure that out from the current man page isn't exactly easy.
Apparently the `info' pages are better learning tools in that they're more geared towards new users (I've not spent a lot of time looking at the info pages, so this is a second-hand opinion). On the other hand, the interface for info pages (do an `info tar') isn't the most user-friendly thing in the world.
What I would like to see (and what I keep getting on soapboxes about after I've had a pint or two at the pub) is a fully cross-platform, xml-aware, user-friendly, Mozilla-based help browser. Yes, there are a lot of buzzwords in that description, but I still think that it would be a phenomenally useful tool. Providing a usable interface for online help is at least as important as having usable content to display within that interface.
After building the help browser, the next step would be to build an easy-to-use integrated authoring system. That's a bit more challenging, of course, but not unrealistically so. The easier it is for people to write documentation, the more documentation is likely to get written.
If these tools existed, then it's likely that the Open Source community would begin generating more and better content -- `reference' stuff like man pages, `learning tools' like info pages and HOWTOs, and more. In my opinion, being able to create and automatically cross-reference all this stuff and have it all display nicely in a clean interface would go a long long way towards making Linux easier to learn and use.
If anyone's interested in helping me design and build this stuff, let me know :)
Who is the target audience?
by 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)?
Deb:
One of the most important things to do before starting to write documentation is to define your audience. Who are you writing for? Kernel hackers? New users? Advanced users?
You cannot write documentation that will be useful for everyone. That's just reality. As I said earlier, you're either going to end up with a huge mess of a document that won't be of much use to anyone, or you'll end up with a really "generalized" document that won't be of much use to anyone.
So, to answer "is there a compromise between the two?": No. Not really. You have to figure out who you're trying to address in your document, and just focus on that one particular audience.
Embedded Documentation/Extracting Docs from code
by 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).
Deb:
Okay, if I understand the question correctly, you're asking: do I think that we will eventually generate documentation from source code?
Well, it depends what sort of documentation you're talking about. If you're talking about documenting the code itself, maybe/yes. But if you're talking about user documentation, no. User documentation should be task-based, telling the users how to do the various things they want to do. Documentation generated from code is more likely to be feature-based, talking about what the various functions and features of the software are, etc.
Task-based and feature-based documentation are very very different things.
All that said, I want to make an amendment: where I said "no", I really meant "not yet". There are some really interesting technologies out there, and some really smart people thinking about some of this stuff. It might very well be possible that we could eventually create a system that allows us to auto-generate a lot of documentation from code. Right now, however, I cannot see it becoming a reality in the near future (feel free to start hacking to prove me wrong ;)
Also keep in mind that this question ranges a little bit away from my area of expertise. My official answer really is "I don't know", so if I'm completely wrong on this one, feel free to correct me.
More importantly, perhaps, do you think there is any reason to develop a XML dialect specifically for documentation?
Deb:
Well, there is one: DocBook.
Ok Deb, tell me...
by 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 meet 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.
Deb:
Sorry Robin, this one is far too political and way too off topic.
- deb
I'm dissapointed with Deb's last answer. I didn't ask it, I didn't think of it before it was asked, but upon reading it I think it does need to be addressed even though it was offtopic, and I'm dissapointed with Deb not giving *any* answer at all.
Women want to get into technical open source areas, so they make a site to promote that, thats great, more power to them. I'd like to see more women in the movement. But then turning this site into a way to make women centric distributions and male bash? Nah... That does nobody any good.
What would a womans distribution have that a mans one wouldnt? Why do they need to be different?
Its software, its programs, its non-gender specific.
-- iCEBaLM
Q1) Re: Dynamic user-level docs
So maybe there isn't a dynamic document that will tailor itself to the skill level of the user reading it. Personally, I'd be frightened if any piece of software were psychically-enabled. But seriously, help docs in plain ol' HTML could work pretty well, with some simple design, such as:
Top-level page is newbified
Has links to most-common scenario HOWTO's
Links topics to sub-pages with detailed nuts & bolts for the technically minded; this makes the topic organized and navigable, unlike man pages.
Q2: Document Version Control
I have to agree with Deb that keeping a writer around whose existence is justified by keeping the documentation current with the code can solve the problem. But for those open-source dev groups that still have to write the docs for their publication dept. (be it Kinko's or internal), I'd think keeping version/release numbers with the docs could help. That way, new release = time to write new docs. (Just what did we change this iteration?) It also lets users prod you for the documentation for v0.8, since the docs zipped with the source are v0.2.
Q4: Translating Docs
I remember from my technical writing class some guidelines on documentation. Things like never use cliche's, idioms, Un-Defined Acronyms (UDA), etc. Following some of those I'm sure would go a long way to making works easier to translate, or at least read for ESL readers. (Oops, TLA.) It's similar to the philosophy that writing good code makes code that's easy to use, maintain, expand, port, etc. Writing a good doc makes it easier to read, and probably easier to translate.
Q6: Coding in DOC :P
Learning at least a little bit of how to write technical documents is important. So much so, that it was a mandatory part of my UG CS program.
So books are good. Find a good book, and Read The Fine Manual on how to write technical documents. When I went to search fatbrain.com for the technical writing reference guide on my shelf, all I got was:
Q8: Man Pages
No manual entry for Pages.
MY opinion on this is just my HTML idea as up in Q1. Maybe even convert man to HTML, and link that top-level newbified doc to specific anchors in the ultra-technical man page.
Q10: Auto-documentation from source code I think Deb's right, in that user-level documentation probably won't come from the source code. On the other hand, some really handy information about that source you're distributing will come from the Rubbish Lister! :)
Q11: LinuxChix/Feminism
I wouldn't touch this question with a 10-BaseT cable. Besides, I'm not qualified, and I know my limits.
Yes, we understand these tags always apply: fud, dupe, typo, slashdotted, topic name