Please create an account to participate in the Slashdot moderation system

 


Forgot your password?
Close
typodupeerror
×
Programming IT Technology

Ask Deb Richardson About Open Source Documentation 88

Posted by Roblimo from the unsung-Open-Source-workers dept.
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.
This discussion has been archived. No new comments can be posted.

Ask Deb Richardson About Open Source Documentation More

Ask Deb Richardson About Open Source Documentation

Comments Filter:

  • Debbie does slashdot (Score:1)

    by Anonymous Coward
    ;)

    --
    The Cabal that doesn't exist

  • Re:Debbie does slashdot (Score:1)

    by Anonymous Coward
    Deb, are you a lesbian ? Why ?

    Thank you
    --
    What do you mean "cabal" ?

  • Integrated Help System (Score:1)

    by Anonymous Coward
    What is your opinion on an integrated help system or expert system to assist users with open source setup and maintenance issues?

    Such as system might integrate howto's, files like in /usr/doc, man pages, etc. It might allow disk or CD-based searches of relevant topics as well as Internet-based search. It might be oriented toward setting things up and fixing problems, not toward reading 20 pages to find something you really need that could be expressed in 10-20 lines?

    Remember the RedHat User's FAQ? The Linux Knowledge Base? Both are a start in this direction?

  • Deb,

    As someone who has written 100 page+ user manuals for a software product, I am often frustrated that I have to repeat so much of what I consider to be "core" Unix knowledge or standard system procedures. The product in question sometimes requires knowledge of networking, SCSI and disk management, application control, etc. There is pressure from marketing to document every step of installation and configuration in complete detail as "hand-holding" for customers, yet when I cover some of the required procedures I:
    1. repeat information available elsewhere, typically in the OS vendor's documentation;
    2. duplicate similar information for each supported platform;
    3. risk the manual becoming outdated or incorrect when those procedures change in future OS upgrades.


    Isn't it time we promoted reuseable documentation? With the ubiquity of hyperlinking, I should be able to create links (optionally "inlined"!) to external documents covering relevant procedures and background. Other writers should then be able to subset all or part of my document for their own work (say, if they were documenting add-on components).

    Programmers are able to pull in object libraries and modules; wouldn't it be incredibly useful for technical writers to call on similar resources? I foresee a need for standards if this is ever to become feasible. Could the open source movement set these standards and shake up another area of software development?

    Cheers,
    Ade_
    /
  • I am a bit or a programmer, and I have a good abbility of being able to write short, concise documentation, but my questions is what do you think of documenting programs like javadoc & doc++, I use both (depending on language, of course), and I know they are really only programmer documentation, but, if maintained correctly, can give document writers a better idea of what they writing, if they are programmers themselves...
  • Deb,

    Do you believe in literate programming? The Linux kernel has just started to include DocBook comments and scripts to build documentation.

    It seems to be a bit like snake oil in that it is supposed to solve all our problems, and as a programmer (==born optimist), I tend to believe this.

    I am not sure however if this is the way to go. A friend of mine works at a company that has dedicated documentalists which continously bother
    programmers with questions on what they are doing.

    What are your thoughts?
  • HTH. HAND.
    --

  • Questions first:

    Should programmers even be allowed to write documentation?

    Should documentation be customizable to specific users, or should it be more general to explain the underlying philosophy of a program?

    Explaination of questions:

    Programmers are rarely good documentation writers. At least, that's the common wisdom. More importantly (I think), programmers should not spend the creative energy on documentation, and let somebody who isn't such a good programmer but is a master wordsmith fill in those cracks. But I'd be interested in your opinion on the matter.

    I can think of how a documentation system could be combined with a relational-DB to provide a single-source document that is specific to a person's installation. So, a user who installs KDE (but not GNOME) would never even have the information on how to set up a modem with GNOME. This would provide nice step-by-steps, but would not teach the underlying technology of negotiating with a remote host, interfacing with a serial device, etc. Which is better? A deeper understanding or end results?

  • No problem, this is OT, but here's how you do it:
    • Compliment something about linux. Say that Open Source allows rapid development, for example. Doesn't necessarily have to be related.
    • Make a disclaimer: "I use linux, and it's great, but.."
    • Use any of the following to "soften" the statement: probably, technically speaking, usually, generally speaking. If you're wrong, you don't look as bad.
    • Stick to the facts. If you offer an unsubstantiated opinion, you'll be flamed and/or moderated to oblivion. Avoid holy-wars! Do not say emacs or vi sucks and joe rules. Again - keep it factual so they don't have a leg to stand on if/when they flame you.
    • DO NOT make it personal. Don't say Rob sucks, or RMS is a blow-hard. You'll surely be ignored.
    • Try to quote people already considered 'in' the community. Quoting ESR or RMS is essentially like quoting the Bible to a Christian - who the hell is going to argue with /them/?

    This is coming from the guy most-often referred to as the karma whore on slashdot, so I think I know what I'm talking about. If you want, my e-mail (above) is valid, feel free to discuss this in a more private forum. It's also easier to keep track of. =)

    In short, argue as you normally would, but don't step on people's toes while doing it. Mud-slinging is out. No matter how stupid somebody else's opinion seems, treat it as equal to your own. ie: respectfully disagree with them. And it lends more credibility to your side if/when you don't resort to such tactics.

    ~ Signal 11

  • Something like a "Linux Users&Developers Network"
    with a nice interface for offline usage would be wonderful. A distribution which can be partially or completely updated from the internet with a few mouse clicks or comands would be really nice.
    Are there already plans for such a software and distribution project?

    I definitely have to learn about SGML to take part!
  • Deb,

    What's your assesment of the current state of documentation tools that writers for Open Source projects use? It seems that most projects, such as the Linux Documentation Project and GNOME, have standardized on DocBook. Are you happy with the Cygnus DocBook tools or do you sometimes find yourself wishing you were using a commercial document prep packages such as Quark or Framemaker? If so, why? If not, why are the free docbooks tools superior?

  • Browsing through the OSWG site, I notice that it has sections for volunteer writers and editors. Has this been successful so far, in helping volunteers find projects and vice versa? If not, what needs to happen before it takes off?

    --
  • Maybe we should start recognizing the docs writers as we do with the software writers. Awards or something.
  • Yep.
    Open Source Writers Group [thepuffingroup.com]
  • SGML/XML + Docbook seem to be the markup languages & DTD of choice for writing and maintaining documentation in different formats (GNOME [gnome.org] uses it, for example). However, there's a pretty steep learning curve for creating documents with Docbook, and figuring out how to convert SGML to a readable format (HTML, text, RTF, whatever) can be a bitch. Jade ain't exactly simple and intuitive.

    What would you recommend as the best-of-the-best open source tools currently existing for creating portable, modern documentation? And what tools are needed that don't exist?

    Please be specific. What would you tell a complete newbie to set up on their machine in order to start writing portable, extensible docs?

    Thanks!
    W
    -------------------

  • Hello Deb,

    How would you describe the state of Linux documentation today? What direction is it going?

    What are some examples of well done documentation aspiring contributors to emulate?

    What question do you wish you were asked that nobody has asked?
  • The GNU system establishes a lot of very useful standards for software development. Although I haven't researched it much, I have no doubt that there are GNU standards pertaining to documentation (man pages and info pages particularly).

    What is it that a documentation standard should address? Although GNU may have recommendations for providing info pages with programs, I don't imagine the FSF telling the developer how they should be written; nor are info pages necessarily the way many people would want to see their documents.
  • Will you teach us what the elements are of good documentation? Overviews, outlines, and best of galleries that we can use for inspiration. What pieces of documentation are the most important to get done first?

    Codify some standards of good documentation. There is some consensus about what makes up specific types of documentation such as man pages, HOWTOs and readmes. How about user guides and advanced technical manuals?

    There are many references to RTFM and RTS (Read The Source) but as the community has grown we have not responded well to a need for documentation that is usefull to noncoders. I have been through a great deal of frustration with undocumented, mis-documented, and out of date documents. I have usually dealt with this in an evolutionary manner, by not using the software.

    Browsing the OSWG website I see a great resource for finding existing documentation, but what about a resource for creating good documentation?

    chris
  • In Linux documentation, I've often seen a bad explanation of something or thought of a better example, but I'm hesitant to try to make suggestions. I'm afraid that I'll come across as some kind of anal-retentive perfectionist, or that I don't appreciate the hard work that went into the current version of the docs. What's the best way to make suggestions for small or even large changes or corrections in documentation without offending the author?

    main(O){10<putchar((O--,102-((O&4)*16| (31&60>>5*(O&3)))))&&main(2+O);}
  • You're absolutely right, documentation is always the first casualty of bug fixing. The trick is to make it easy to for programmers to keep documentation up to date.
    I would like to see something like the javadoc tool for Linux source, that would make it easy to keep a low level technical and system knowledge base up to date and which could be used as a reliable reference for people writing higher-level "new user" documentation.
  • Let people put their name against it, and be immortal forever.
    BWAHAHAHAHAHAHAHAHA!!!!!
    Seriously, the real motivation for contributing to any open source project has always been to be able to say, "I did that and now everybody's using it."
  • Part of the reason that Open Source came into existance was a culture amoung programmers that valued sharing work, re-use, and value placed upon intellectual labor rather than on intellectual property. This culture does not exist yet for writers.

    Do you think that the net, weblogs and the Open Source movement will change the culture of writing significantly enough so that writing joins the gift culture of programming? Or will Open Sourced writing always be attached to programs and platforms and done mainly for religious reasons?

  • I think open source documentation gets a bad rap. Personally, I find it to be superior to anything coming out of the MS camp. With open source software, I can find detailed documentation and examples on the web, on the fly. When I look for documentation for MS products, it's usually lacking. They're either trying to push another manual or get me to spend money in other ways. Who cares if MS manuals are written more professionally if they are going to milk you for all you got and you don't have access to the information when you need it?

  • since I've been starting with Linux a couple of years ago as a complete UNIX illiterate I've always found the piece of information that I needed to accomplish something. For almost everything there is documentation available for newbies as well as gurus. Working in the IT industry I have rarely seen commercial software with this amount of usable documentation.
    There is one point, however, that really needs to be improved: we need to organize all the documentation in a way that makes it easier to find it.
    One gets spoiled so easily when using OS software. And yes, it's important to push things to get even better. But we should also spread the word that there is great documentation available for most packages TODAY.
  • Kirrily Robert, aka Skud, has written on this already; see her paper geek chicks: second thoughts [netizen.com.au]. Basically, she points out that because the OS community has valued "hard skills" (the ones closer to the machine) so much, people with soft skills (like documentation, internationalization, etc) haven't been encouraged. And, she argues, many of those skills are "traditionally female" skills.

    IOW: if the OS community wants documentation that doesn't suck, it needs to encourage all those females who've been writing documentation or doing tech support professionally to contribute.

    IMO: Given the flamish environment of many geekish circles, it's not surprising that females with more elevated social circles have stayed away. If I thought "the OS/Free Software community" == "Slashdot" I'd stay away too.

  • Plenty of people complain about poorly written, poorly indexed Linux, *BSD, and Open Source documentation.

    Then they find deja.com.

    But seriously, I think the complaint of "where's the docs" is a little overdone. Sure, you may not have a hefty "Linux Bible" taking up most of your shelf-space, but so what? The OS is a "new paradigm", why shouldn't the documentation of the OS be the same way?

    Let's deal with the supposed problems one at a time:

    1) Hard for newbies to find help. How about the mailing lists setup for just this purpose? I'm sure I'm going to hear a lot of complaints that "this doesn't work for everyone" or "all I ever got from l-n was 'RTFM'". That leads to points 2 and 3.

    2) RTFM is an entirely reasonable response to an unreasonable question. It may not be polite but it IS the correct solution to the user's problem. User wants to know what the "-l" flag to "ls" does. The Right Solution(tm) to this problem is RTFM. In this case, "man ls"

    3) Everybody and her dog is setting up a Linux newbie site, visit those. Or search usenet. Or join a users group. There are more Linux help channels than for any other software I could name. Newbies that know what they want and are willing to look around are well-supported. Newbies that don't know what they want and/or aren't willing to look around can't be helped by anyone.

    4) How about the claim that "unpopular" software (i.e. not-apache and not-samba) has little documentation? Yep, that's somewhat true. For instance, netatalk (makes Linux talk to Macs) was a bitch to setup. Until I joined the mailing list. For the occasional piece of software that doesn't have a mailing list, read the code.

    5) "Read the code"?? I'm not a programmer and I shouldn't need to be understand how to use package XYZ. You are right. For this small subset of software we need better docs. What subset is that:
    • Hasn't been well-trodden by newbies
    • Doesn't have a website
    • Doesn't have a mailing list
    • Doesn't have a maintainer with a valid email address
    • Doesn't have a well-documented, viable alternative

    How much of the software out there meets these criteria?

    SOOOoooo, my question to Deb is: What categories of software do YOU think are most in need of documentation and why do you think that?
    --

  • Boxers or briefs?


    --
  • Being a programmer, i find it hard to write documentation, much less good documenation. i have always seen packages that take source and turns it into documents (like cxref) and wondered if they are really worth using, or if i should just stick with SGML. Do you have any thoughts on systems such as these?

    i know i'm only supposed to ask one question per post, but as a followup, are there any really good documentation systems you recommend? SGML and LaTeX are nice, but are very often inflexible and obfuscated. Usually when i want to make portable docs with graphics i just whip out one of my standard HTML templates and go to town.
  • I do not have the time or resources to actually do any work (plus my spelling and grammer suck, totally) but I would still like to do something to help. My question is -

    Is there a way to donate funds/money to help the documentation cause?

    ---

  • Why have you chosen to refer to the documentation
    as "Open Source Documentation" instead of "Free Documentation"? Do you feel that the Open Source Movement is better or more important than the Free Sofwtare Movement?

    Have you considered integrating with the GNU project documentation efforts? The GNU project has long had documentation as a top priority. Why not integrate with their efforts?

  • Having gone from DOS to OS/2 to Win95,8 and finally Debian, I must say the hands down best documentation was 4DOS. Instantly available, context sensitive, combining the best of man pages, HOWTO tutorials, and a hypertext environment, it kicked butt and took names.

    The man page for LILO, for instance, mentions that the lilo.conf option "linear" substitutes linear HD addressing for cylinder/sector/head addressing, but does not mention why this option is present. Neither does the mini-HOWTO for LILO, for that matter.

    End-user documentation may be the last frontier in Linux. Man is convenient, but often incomplete or not enough of a tutorial (and, as a quick reference, should in and of itself perhaps not be a tutorial). If info/pinfo is to be useful, it could and should take these two needs into account.

    In the meantime, see you on debian-user@lists.debian.org. :)

  • What are some examples of existing open-source documentation that illustrate the writing principles you're talking about, or are examples of overall well-written docs?

    --
    Fourth law of programming: Anything that can go wrong wi

  • Doxygen and DOC++ are available. They're like javadoc for C++, I assume they would work for straight C.

    They're both GPL, I believe.

    I use Doxygen on my projects; it works out pretty well.

    I think KDE uses something called KDOC, which is built on doxygen.
  • Related question:

    I've heard some stuff about XML docbook formats, and would be interested in hearing what you have to say about that, but more importantly, I feel that there isn't really a good tool out there to allow distributed, collaborative, open-source style documentation.

    I've heard CVS is the greatest thing since sliced bread when you have multiple people working on the same codebase. Documentation doesn't have any sort of "killer app" that makes it easy for people to contribute.

    Would you describe an ideal (probably web-based) tool which some open source hackers could start working on to help improve the state of documentation?

    --Robert
    (sorry for rambling)
  • Thanks for the thoughts. They kinda jobed with my reflex.

  • Why do you think this format been abandoned as the linux documentation standard?
    ---
  • 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?


    I would like to see an answer to this as well, for all of the same reasons. One of the problems with translations of Open Source documentation is that the current audience is rather small in some cases. The reason is that English is the lingua franca of software. Thus, the translations are being done in many cases for a hypothetical future audience. The people currently using open source are frequently capable of reading the English documentation. And yet relying on that limits the future spread of open source beyond native English speakers and fluent non-natives.

    As for finding translators, I'll plug the Free Translation Project [umontreal.ca] as I always do when this subject comes up. There is nothing wrong with starting another project, but the people involved in this one are a good source of ideas and volunteers. Don't ever forget to talk to us. We want to hear about free software internationalization and localization efforts.
  • This is just a primer to get people thinking.

    If the documentation says it does this, but the source says it does that, what does it really do? Or, to put it another way, isn't Open Source the ultimate documentation?

    This question submitted by one who knows the value of good documentation.
  • Is there a convention for submitting a suggested change to a document?

    I seems to me many of these would have to take on the form of a discussion, and what's clear to one person may not be a clearly superior description to another.
  • You are absolutely rigth. That's why general docs, reference manuals and tutorials are written. They are meant for people who want different things.
  • I'm wondering, is this the same Deb Richardson that went to Acadia University?

    ~CP

  • Once again, Roblimo tries to pass off as original material that has already been submitted. I posted the following submissions:

    Here are your recent submissions to Slashdot, and their status within the system:

    2000-03-15 16:47:30 Keepers of the Flame (articles,linux) (declined)

    2000-03-15 06:03:54 LDP and OSWG: Room in town for two? (articles,news) (declined)

    Notice how both were declined. Suddenly, Roblimo decides to "revisit" the open-source world. Gee, Rob, where'd you get that idea from?

    Could it be that the reason my submissions were declined is that they refer to http://www.nerdperfect.com [nerdperfect.com], another tech newssite?

  • You write them for both the geek crowd *and* for mom. The trick is in your basic assumptions and in intelligently laying out the information for each reader/user. Whoever gets to the README knows how to ftp or at the very least how to steer a browser. With a browser, you can hyperlink to other tutorials for daunting technical problems like how to run make (obviously, we're already out of man country). Present succinctly the obvious-to-geeks stuff right up front, reassure, and unpack and provide details as the user demands them. HTML affords a tremendous advantage if you can grab it by the horns: the user gets to pick and choose a meaningful "narrative," and doesn't get a wash of useless info up front if he/she doesn't understand it, want it, or need it.

    KDE has gotten halfway there by having online help files on many of their apps. Unfortunately, the help files aren't particularly helpful. If I'm trying to get help, I don't want to know who designed the software or how to use its nifty features--I'm here because I can't get the nifty features to work! Obviously, every system is different, and no interactive troubleshoot interface is going to be able to address every problem, but an interactive, problem-to-solution based FAQ would be a nice documentary standard for ostensibly user-friendly interfaces.

    This stuff is important: if Linux is ever going to make a serious dent on Bill's OS at the desktop, K (and Gnome, and Enlightenment/AfterStep, etc.) are going to have to pull up their socks in the documentation department. Good writing should be regarded as an integral aspect of good interface design.

  • Is the Open-Source Doc movement an attempt to make Linux more usable by the "common man" who is used to Windows, or is it simply a collection of FAQs and man pages which are useful to the hacker-type userbase Linux already has?

    The Linux movement may have more and better developers than Microsoft, but Microsoft is WAY ahead in categories like usability-testing and documentation. Why did MS add a "Start Button" in Windows 95? Because the most often-asked question by newbies when they sit down at a computer is: "Where do I start?" MS tests its products with users and pays attention to their complaints.

    When a user says: "I want Windows to do XXX," MS doesn't reply: "But doing that would slow the whole computer down, and it would be difficult to maintain, and could easily break, and above all, it wouldn't be ELEGANT!" When enough newbies say they'd love a friggin' dancing paperclip to tell them how to do a mail merge, MS does it.

    I'm very happy to see an online documentation center. But what about an effort to design user interfaces which work well from a user's perspective? If hackers design programs, they're going to be usable only by hackers, and providing good documentation isn't going to fix the problem. We have window managers like Gnome and KDE which "look-and-feel" a lot like Windows, but under the surface they are really as much a hacker's project as gcc. I don't expect gcc to ever be usable by a newbie, but the windowing environment has to be well-tested and well-designed from a user's perspective if we're ever going to have a broader user-base.

    Have any of the Distributors looked into providing links to the OSWG on their desktops, or from their help options? It would be very nice for a user to be able to link directly to the OSWG's archives when he/she presses the help button.
  • Seems to me that the problem of keeping documentation current is especially tough in a distributed situation, when you might have different versions of a document living in different databases.

    Do you have any thoughts on how various open source documentation projects (OSWG, LDP, LKB) could collaborate on this or similar problems?

  • Total revamp? (Score:2)

    by Anonymous Coward
    (I know I'll get moded down since I have something critical to say of Linux...but here goes)
    Plenty of people complain about poorly written, poorly indexed Linux, *BSD

    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 /etc or what things go in /usr/local thats not cool.

    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 /usr/doc/, /usr/info/, the manpages, etc. i was impressed with the 'afterboot' manpage in OpenBSD 2.6. It explained what needed to be done, when, and WHY after install. This is a far cry from RedHat's "Reboot your machine and pray you aren't rooted in 10 minutes."

    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
  • Some experts cite the poor/widely spread/differently formatted documentation as a sign that open source software in general and Linux specifically isn't a mature platform. I personally haven't found this to be the case, for example the Linux HOWTO pages are more useful than most manuals for closed source OS's.

    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?
    --
  • 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...
  • I'm a young (second year of college) woman in the Bay Area. I've done two stints of summer tech-writing internships. The first summer, I actually got to work in the same cubicle-group as the engineers, and I feel as though I actually got some work done. The second summer, the company had grown bigger and more corporate, and I worked in a separate "tech writing" group where I had little contact with the engineering group, and my objectives kept changing and I felt bored. It was frustrating work and I left early.

    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.

  • FYI (Score:2)

    by shomon2 ( 71232 )
    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 [linuxchix.org]

    Ale
  • The Open Content web site contains a brief article [opencontent.org] 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?

  • From the OSWG Mission Statement: [oswg.org]

    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 [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?

  • 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 [stat.ethz.ch] 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.
  • 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."

  • Perhaps the obvious question, but one to be asked. (Score:3)

    by Mercury ( 13121 ) on Monday March 20, 2000 @07:23AM (#1189769)
    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.

  • 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! [cthulhu.org]

  • Women, computing, Open Source (Score:3)

    by Hard_Code ( 49548 ) on Monday March 20, 2000 @07:30AM (#1189771)
    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? (Score:3)

    by Jerom ( 96338 ) on Monday March 20, 2000 @07:09AM (#1189772)
    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 (Score:4)

    by Ed Avis ( 5917 ) <ed@membled.com> on Monday March 20, 2000 @07:26AM (#1189773) Homepage
    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 (Score:4)

    by Signal 11 ( 7608 ) on Monday March 20, 2000 @07:21AM (#1189774)
    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 (Score:4)

    by Duke of URL ( 10219 ) on Monday March 20, 2000 @07:09AM (#1189775)
    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? (Score:4)

    by Seth Scali ( 18018 ) on Monday March 20, 2000 @07:28AM (#1189776)
    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
  • 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? (Score:4)

    by Noryungi ( 70322 ) on Monday March 20, 2000 @07:11AM (#1189778) Homepage Journal
    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!
  • 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) (Score:5)

    by Xiphia ( 134120 ) on Monday March 20, 2000 @08:23AM (#1189780)

    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 [linuxchix.org]? 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.

Slashdot Top Deals

It isn't easy being the parent of a six-year-old. However, it's a pretty small price to pay for having somebody around the house who understands computers.

Close