Deb Richardson Answers Open Source Doc Questions 68
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
Men, Women, and Linux (Score:1)
***Trolls are neat-o!***
Re:Womyn and Linux (Score:1)
Nah, because y'all scare the ladies away.
Anyway, yes, I agree she totally wussed on that last question. Christ, if you're not willing to talk about your own damn project, what does that say?
Anyway, I'm sure we'll be seeing more women in the arena, since now there's more than just the pursuit of geekiness..there's a whole boatload of money out there.
Flame on..
Re:How to motivate open-source doc writers (Score:1)
I've done the same thing right here. I think this is a Bad Idea. Any way to fix it?
Re:Mozilla-based help?! (Score:1)
Re:The tar man page (Score:1)
is about the same - it has those examples. I'm not quite sure why she used that as an example . . .
Re:700 odd people (Score:1)
I'd have thought that odd people would be the ones *most* likely to be discriminated against. Not that I'm saying that they should be.
Re:How to motivate open-source doc writers (Score:1)
That way you wouldn't need to be anonymous here but could stand behind your viewpoint as well as avoid any chance of giving the impression that you'll be moderating any of these comments with an ax to grind.
Re:How to motivate open-source doc writers (Score:1)
If the idea was that good, however(and I'm not saying it wasn't)it could have stood on it's own as an anonymous post.
If you are a dedicated and responsible moderator, then I thank you, as I have been seeing a distressing number lately who aren't. And I'm referring to moderation done to posts other than mine.
Re:dissapearing article (Score:1)
Nice! (Score:1)
Well, I don't know about the rest of slashdot, but I respect someone who lays out the rules and sticks to them. Thanks for being honest, and keeping things clean. It's a rarity around here and it's appreciated.
Re:Documentation Formatting (Score:1)
I agree that XHTML is probably a good starting point for unified Linux documentation. A well designed schema should be able to reflect the features of the other systems, and using HTML as a presentation layer allows for standard, well-known interfaces (lynx, mozilla, etc.).
--
Re:Documentation Formatting (Score:1)
(Of course, the eXtended part of a XHTML documentation schema would need to be designed to handle the structure issues.)
The reason I suggested XHTML is that common, popular, open source renderers already exist and could be easily extended to handle a common documentation format. Yet Another SGML/XML format that requires it's own viewer/converters is doomed to the same fate as Info or DocBook - nitch penetration, more hassle for users, not less, etc, etc.
Of course, if a Linux distribution shipped all of the documentation in one format, I'd probably be so happy that I wouldn't care what format that is.
--
Re:Documentation Formatting (Score:1)
Of course DocBook (and GNU Info) aren't 'nitch' formats in the sense that nobody uses them. They are, however, sorely out of place in operating system 'distributions' that really should be providing a unified, user-accessible help system.
--
man and help browsers (Score:1)
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.
This sounds like a great idea, except for the Mozilla bit. One feature in such a help browser I'd like to see is to use the XML to allow the user to select different levels of technical detail, both as a default, and within each document. This could also be used to switch between feature-based and task-based help.
The question was originally about man pages, which, in my experience range from excellent to useless. While developing a super-spiffy FBC help browser is a useful thing, the concept of man pages isn't bad, just the execution. There are lots of man pages which seriously need improvement. (Like tar.)
Re:Dynamically updating documentation for new user (Score:1)
Honor will wont pay your rent.
Bowie J. Poag
Re:The tar man page (Score:1)
man -k provides some of the functionality you want, and man -K is even closer although quite slow and not available for all versions of man, but you're right: it's not a novice-friendly medium. man pages walk the fine line between being terse and being cryptic.
--
Re:Mozilla-based help?! (Score:1)
I disagree (Score:1)
I agree that man pages are horrific to learn things from, tar being one of the worst. I suggest that they should be in the following format:
Stock Options for Open Source Writers (Score:1)
I've written programs, as well as the User Manuals and Technical Docs and Online Help, both in English and French myself. I used to get into arguments with some of the translators over which words to use - the "official" word (thought up by some bureaucrat and way too long to remember), or the "common usage" word. Some of the computer words in French, for example, are way to long, and most French speaking users don't use those words.
But Stock Options might be cool. Any project needs writers, who should be on par with coders. A good technical writer understands the code, while being apart from it that they can explain it simply in a few short descriptive action phrases.
I've been meaning to look into doing docs, since that is the area I think Open Source projects are weakest on, and it's easy for me to gen words.
But first, I've got some boxes to unpack and servers to nail down. Then I'll try to help out. After all, Open Source has been very, very good to me, in terms of IPOs.
Re:Puns and jokes (Score:1)
the same time, you should be in another field,
like maybe accounting, were lack of imagination is
an asset, not programing. Or are you just sore that
the doc writers are more clever then you. Good
thing that people like you are in the minority in
the techy fields or else we would all die of bordom.
Personaly, I find books like "The Standard
C Library" by P.J. Plauger, much more usable
because of the lightness (like the THX1138 ref).
This is a book I refer to often. If you had
writen it I would be cursing your name daily. But
fortunatly Plauger wrote it, so not only do I get
a refrence to the C Library, I get a witty narative
that not only keeps me awake while plowing through
an awfully dry subject, but provides me with some
insight as to why the Standard C Lib. is the way
it is.
excellent interview! (Score:1)
No useless comments, just content that makes its target.
Kudos for such a great job.
jaime.
Today's Quote (Score:1)
How come you always here this phrase in movies, "This guy is either really smart or really dumb"? Are the actions of these two very different groups that similar? If so, then maybe employers should start hiring really dumb people, they work cheap and they get the same results as really smart people.
Re:Puns and jokes (Score:1)
Your confusing bad writing with lack of humor. Well-written documentation makes the subject interesting without having to add a 1-inch layer of sugar. Note that I did not say that we shouldn't have relevent anecdotes, or any attempt to "personalize" the information. What I said was that I don't want cutesy off-topic garbage that makes it harder to find what I'm looking for.
If you can't process knowledge and puns at the same time, you should be in another field...
Perhaps if programming is not interesting enough for you to be able to process information without cutesy entertainment, you should be in a field other than programming.
--
Re:Punny Documentation (Score:1)
Re:Mozilla-based help?! (Score:1)
Re:Punny Documentation (Score:1)
Well, I was just pointing out, by means of parody, the silliness of this elitist view of "I can understand source code, I don't care about docs", which, as you pointed out, is one of the reasons why open source docs aren't better than they are today.
Punny Documentation (Score:1)
Awwww... now there is no more reason for us to even read the docs any more... aren't all those insider jokes and puns what documentation is really about? I mean, who wants to read a serious, down-to-earth doc with no puns, no jokes, when we can all read the source and find out how it works anyway?
:-)
This is a good idea (Score:1)
Re:Mozilla-based help?! (Score:1)
For the billionth time, people, it's a damn debug release, it's supposed to be bigger and slower.
But, in any case, I have to disagree with you. Mozilla shouldn't be the only help tool, but an XML based help system would be nice. Then it would be possible to write an XSL transformation to view it in Mozilla or a second transform for the command line (or a third for something else and so on). This way the data is written once and just presented differently depending on how you access it (pretty much the whole point of XML/XSL anyway).
Re:Dissapointing... (Score:1)
Her purpose here, (the way I understand it) was to answer questions dealing with OSWG, her involment with it, and techinal writing in general. I don't think (IMHO) she would want to get into the indepth issuse as "gender and computers" during this interview, there is just to many ways it could go.
Post it to AskSlash??
Collaboratively written documentation (Score:1)
This is a great idea, and well-implemented, I believe it can become a very useful tool for writing the doc.
We can consider it as a kind of "Content Management System". Any author (and it should be easy to be one) can come and edit a doc (of course, there is versionning) or start a new one and these can be review by all or specific people (editors...). After some favorable judging (to be defined), the doc can be part of the public doc release and so on.
At a more basic level, this kind of thing has been done a thousand times on the web (there is even a problem set part of web development course asking to implement just that cf. http://namin.arsdigita.org/dev/p sets/ps3/home.html [arsdigita.org]) This is really just an outline of what a content management system should be.
By keeping everything nicely in a database, we can generate all the interfaces (XML, HTML, etc.) from a single format.
I'll try to work on this. If anybody wants to join...
Re:Dynamically updating documentation for new user (Score:1)
Maybe I should just carry a stack of NDAs wherever I go.
I have an idea for a handy piece of software, a few years ago I would of written it and posted it somewhere. Now I think if I write it, someone else (like RH) will put it into there package , hype it up as theres to sell more of there products. Meanwhile I get the 'honor' of knowing I wrote it.
Re:Dissapointing... (Score:1)
Re:Dynamically updating documentation for new user (Score:1)
Effective user assistance (a much more meaningful term, btw, than documentation - documentation is just one piece of user assistance along with user interface design, usability testing, hci, etc.) is a tough problem.
Many people have, and will continue, to spend their entire lives looking for the answer to the question "How do we help users effectively use our software tool to do the work they want or need to do?" It's not too difficult when you are dealing with a small, specific group of people (like the original users of Unix, for whom man pages were considered great UA), but when the audience gets larger and more diffused, effective user assistance becomes very difficult.
The problem is that almost everyone needs UA that has been personalized, and the creators of the UA cannot personalize the software for everyone. Why? Because I don't, and I can't, know what assistance you need. If I knew, I'd fix the program so you wouldn't have to ask the question.
As UA systems become more advanced, more things are possible, but giving perfect assistance to every user is, well, if not impossible, nearly so.
If you know the answer, I suggest that you create a company and market it, not to make money, but to help the millions of people that everyday fail to use their software tools effectively.
Re:Take Deb's gender out of the discussion (Score:1)
What concerns me, however, is that she is recieving negative feedback from folks because of her linuxchix activities. Why? I didn't see where linuxchix and the Documentation project had anything do with each other, except that she was involved in both.
Documentation Formatting (Score:2)
Please, no. HTML does not specify enough structure to adequately represent even a simple manpage. (It doesn't have, for instance, any idea of a section with a section title -- just headlines and paragraphs, not associated with one another.) XML, on the other hand, sounds to me like just the thing, because it makes it possible to specify structure more precisely, and to require that certain kinds of information be present or associated.
The biggest problem I have with the current state of documentation for Linux-based systems is its inconsistency. Debian, for instance, is a great system, but the state of its documentation is a mess. Half of it is in gzipped ASCII and HTML files in /usr/doc, a third in manpages, and the remaining sixth in the accursed GNU Info nonHTML-hypertext system (a plague be upon it).
Anyone building a new help/documentation system should take that problem into account. A new system must subsume all heavily-used existing systems. Either the existing manpages, Info nodes, HOWTOs, and the like must be converted to the new format, distributed as such, and maintained; or the new documentation browser must be able to reference, index, look up, and present the old formats.
I would not mind one bit if DocBook or some other XML DTD were used for all documentation under Linux. I would mind extremely if XML documentation became merely another kind of documentation I had to keep around alongside manpages, Info nodes, zipped ASCII, and HTML.
Re:Documentation Formatting (Score:2)
FWIW, XHTML is not the same as XML. XHTML is "a reformulation of HTMLÊ4 as an XML 1.0 application" (to quote the W3C [w3.org]'s take on it [w3.org] ... and they should know. XHTML can be displayed by ordinary HTML browsers like the one you're using now, but it can also be parsed by an XML parser. It's basically a transitional form ... getting people used to writing formally correct XMLish markup while there aren't yet enough XML tools out there.
(In other words, XML is not a markup language; it is a markup metalanguage. XML applications, of which XHTML is one, are markup languages.)
XHTML, because it is HTML, is the Wrong Thing for documentation, because HTML has insufficient structure, and the wrong sorts of what it's got. DocBook [docbook.org] may or may not be the Right Thing for manpages, but the Linux Documentation Project [linuxdoc.org] folks seem to get along with it for HOWTOs, and they seem to be okay at rendering it into text or HTML or various other formats. DocBook is an SGML system and not XML, but that will be changing with the next major revision, and presumably LDP will be keeping up.
Re:Documentation Formatting (Score:2)
Read upthread. HTML does not specify sections, for instance. It is far too oriented towards the appearance of a document and insufficiently towards rigorous document structure. SGML and XML are all about document structure; that is what industry uses SGML for all the time.
(What do I mean by rigorous structure? In an SGML or XML DTD, you can specify that a document of a particular class must have (for instance) an author, modification date, etc. You can specify (for instance) that headlines must only appear at the beginning of chapters and sections, and that different headlines be used for each. If a file does not have the required features of the document class it claims to be (in the DOCTYPE header) then that is a syntax error. HTML by contrast is very loose and unstructured, oriented towards flexible presentation rather than being able to verify completeness. That may be the Right Thing for playing around, but it is the Wrong Thing for manpages, HOWTOs, or books.)
DocBook is hardly a niche application -- O'Reilly uses it constantly, and it is what Linux HOWTOs and other documentation are kept in by the Linux Documentation Project [linuxdoc.org].
That was my point all along, yes.
Mozilla-based help?! (Score:2)
I just started Mozilla and loaded this page. 'top' shows it as using 20M of memory, and it takes about 5 seconds to load on my K6-2/400.
A Help system should be instantaneous and lightweight so that it will be there as soon as you call it, so that you can keep it around all the time.
Of course, if you actually meant "a custom app based on gecko", that might fit the bill nicely. May I sugest you take a look at Mac OS's Help Center application? It's a HTML-based help system that includes AppleScripts as links in the docs to let users do things just by clicking on the appropriate link in the help pages. How cool is that?
Re:Dissapointing... (Score:2)
I'm not about to start advocating that we allow people to be judged on anything BUT technical skills. End of story. I don't believe in 'equal opportunity' because it's a misnomer - minorities ought to be judged just like everyone else, especially considering they're not a minority.
Okay, enough ranting.
Re:Dissapointing... (Score:2)
It's also irrelevent.
Suppose Rob Malda was being interviewed about the contributions he's made to open-source projects, and the interviewer asked him to defend his support of copyright violation, system cracking, libelous accusations, bad taste, and so on, because he allows anonymous posting on Slashdot. Is that appropriate? Now, I'm sure he can defend himself quite effectively by explaining his views on free speech, and would be quick to point out that he doesn't share the views of everybody who posts to Slashdot. But that's not the purpose of the interview, and it would probably take a lot of his and our time as well as deflecting from the interview's subject. It pulls attention entirely away from the subject at hand--from the realm of information and education to the realm of politics and controversy.
Deb didn't say she would never answer the question (she already has, in other fora). Just that it wasn't appropriate for this interview. The very fact that people were so interested in that particular question--rather than the far more relevent and important issues concerning documentation--shows how much of a distraction it is. For all we know she was burning to answer it, but felt it would be entirely conterproductive to the task at hand.
Re:Dissapointing... (Score:2)
Let's take this one phrase at a time.
Wrap yourself in self-righteousness all you want. She answered all the questions she was given concerning the subject of the interview. Asking for more is simply rude, no matter how strong your desire is for an answer.
dynamic level of detail (Score:2)
I've been wanting to write a physics textbook like this for some time, though here this situation is inverted from computer documentation. The advanced readers want <em>less</em> not more information.
Isn't this sort of thing is what hypertext was meant for? "Didn't understand that? click here to see more steps." You still have to write all those levels, but as far as I can anticipate it shouldn't be too hard to do this by adding some kind of level-of-detail tag to docbook/hypertex, or writing it directly in html.
<i>Trying to address all possible audiences within the scope of a single document is simply a recipe for disaster.</i>
Of course, and textbook writers already do address themselves to a particular audience, and in a formal course environment, you usually want everyone reading the same textbook, at least as a baseline. But though you pitch for a specific level, your audience will always vary in terms of how much detail they want/need to follow you. In the physics example, this is especially true in terms of mathematical background, which has a stong effect on the comprehensibility of the steps in a derivation, but tends to be poorly normalized among the students.
I guess this is a more limited example than what Duke or URL was suggesting, because it's easy to share the introductory text between levels and so on. It's more like hiding detail in optional subsections. I'm not talking about something that would work for both 1st-year undergraduates and postgraduate students. But I still think there could be a lot of use for content levels of this sort on a more modest scale. Does anyone know of any actual examples?
Best of both Worlds (sort of) (Score:2)
You can find pinfo on freshmeat (of course).
Re:Dissapointing... (Score:2)
I encourage you and other folks who think that's the truth to go check out the website and dig into the PUBLIC archives of the lists. You might also be surprised to find out that there are quite a few men on each of the lists.
Grow up and don't be so egoistic as to assume that all women talk about is men when in the company of other women.
-nicole
Re:Dissapointing... (Score:2)
http://www.linuxchix.org/docs/listinfo.html#arc
-nicole
Re:Dissapointing... (Score:2)
-nicole
The tar man page (Score:2)
The tar man page for NetBSD has decent examples for everything from the straightforward tarball extraction command you listed, to using tar for backups, to extracting particular files from a tarball, to adding to an existing tarball...
It may be worthwhile for GNU or the LDP to look at that page.
--
Re:Nice! (Score:2)
Strongly concur. That invitation opened the barn door to all sorts of questions. I'm amused that she declined to address the sexist behavior described by the querent; it appears that she could neither defend it nor admit that it was wrong.
Ghettoization is stupid, and the Frontman Fallacy [acfc.org] is no excuse for it.
--
Re:Dissapointing... (Score:2)
Yes, people can ask any questions they want, and people can choose not to answer those questions, and people can critisize, talk, and say they were dissapointed that the person didn't answer it.
But that's not the purpose of the interview, and it would probably take a lot of his and our time as well as deflecting from the interview's subject. It pulls attention entirely away from the subject at hand--from the realm of information and education to the realm of politics and controversy.
Interviews are not for the interviewee, as the interviewee already knows everything about him/her. Interviews however are for the benifit of others, including the interviewer, in this case, the slashdot populace. This question was the only question moderated to 5, people made it quite clear they wanted it asked and answered, Deb didn't answer it, and she gets critisized for it.
Deb didn't say she would never answer the question (she already has, in other fora). Just that it wasn't appropriate for this interview.
The slashdot populace decides whats appropriate in what questions it asks and moderates up. The people have spoken sir, welcome to this wonderful thing we call democracy. If she already answered it in another forum then she could have provided a link to it instead of rehashing it.
For all we know she was burning to answer it, but felt it would be entirely conterproductive to the task at hand.
Instead she puts her whole interview's credibility into question in my (and others possibly?) mind by not answering a quite straight forward question which the slashdot community wanted most answered. Don't you think that's just a little more counterproductive? I mean why bother with interviews if you're not going to answer the questions most people ask?
-- iCEBaLM
Re:Dissapointing... (Score:2)
You're quite right, I was paraphrasing from what the quesiton submitter said, and without any answer from Deb, I assumed it to be true.
For all we know she was burning to answer it, but felt it would be entirely conterproductive to the task at hand.
That is exactly what I did, this question interested me so much I decided to go take a look at the archives of the mailing lists. Now I only skimmed the subjects and a couple of the postings, I didn't get right down into it. Not only was I surprised by the amount of guys on the list, but I was also surprised to find no boyfriend discussions in the "grrltalk" list, technical topics in the technical list and no mention on the website of a women centric distribution.
From what I saw the questioners claims were unfounded, thats not to say there wasnt any of this at all or more in the past as the list archive only goes back to the beginning of the month. It would have been nice to see Deb say something about this however instead of just letting it slide and making the questioner look like she was right.
-- iCEBaLM
Re:Dissapointing... (Score:2)
Reading your little statement there about "women centric distributions and male bash" proves that you know nothing about what takes place on the linuxchix lists.
and:
I encourage you and other folks who think that's the truth to go check out the website and dig into the PUBLIC archives of the lists. You might also be surprised to find out that there are quite a few men on each of the lists.
Respectively. I really need to use preview...
-- iCEBaLM
Re:Dissapointing... (Score:2)
-- iCEBaLM
Re:man and help browsers (Score:2)
For the AIX man page - tar has several, and you can usually find what you need there...
5. To expand the compressed tar archive file, fil.tar.z, pass the file to the tar command, and extract all files from the expanded tar archive file,enter:
zcat fil.tar.Z | tar -xvf -
granted, they could just put
tar -xzvf fil.tar.gz in this example as well... looking at the tar man page on my linux box, I can see the problem, though... no examples... the BSD and AIX tar man pages are *far* better than the Linux tar man page... why? I'm sure there are other people who have access to these things... grab the man pages from AIX, Solaris, Linux and BSD, check the common flags, steal good examples and descriptions, and make one larger, but better file. Not all of the utils are fully flag compatible in all systems, but this at least gives a good starting point.
Remember also that all of the man/help has to be available through a CLI, since many people run through ssh/telnet sessions, or need the man page to get X running 8^)
Conflicts with moderation... (getting OT) (Score:2)
But you really didn't 8^) (Score:2)
Your proposed layout for the pages is pretty good, but I'd move the overview before the examples, or at least insert a small one or two paragraph "Description" in there, before you get cranking on the examples. The man pages in AIX (I happen to be typing on it, so it's easy to check) are somewhat similar to what you suggest:
1) Purpose (1 line)
2) Syntax (brief list of the options, usually the same thing you'd see with a --help)
3) Description (way too long for 'tar', but for 'cat', a nice 4 line explanation)
4) Flags (in depth explanation)
5) Exit Status
6) Examples
7) Files / related information
Pretty much your overview is their Description, and I think that needs to go before the examples (though a quick link down to all of the sections at the top would be a good idea), and of course the related information could include a bunch of link to external docs,as well as other man pages (grep -> egrep -> fgrep -> http://www.ldp.org/boyisgrepgreat/ or whatever). The order of the layout could vary, but as long as all of hte necessary parts are there, and are easily accessable, you could have a really happy doc that serves both newbie and guru alike...
Favorite AIX 'man tar' example:
7. To archive to an 8-mm device when using the -S flag, enter:
tar -cvf
I mean, weren't you just wondering that? 8^)
Re:Take Deb's gender out of the discussion (Score:2)
Re:Nice! (Score:2)
I feel that the last question asked falls squarely under "Stuff that Matters". I'm pretty sure a good portion of the Slashdot readership agrees with me. It's completely up to the interviewee whether or not she wants to answer the question, but the rules were followed, and the fact that she didn't answer makes me wonder why she is reluctant to explain the views (political or otherwise) she holds.
Or perhaps she just doesn't read slashdot interviews and isn't aware that most people get asked "off-topic" questions. ;)
Puns and jokes (Score:2)
Besides the translation issues, I hope a lot of doc writers will take to heart to just "stick to the facts" and not try to get cute in documentation. I detest having my time wasted with cutesiness in documentation.
If I want a good laugh, I'll read some OSS source code. :) (ha ha only serious)
--
Re:Puns and jokes (Score:2)
I know I'm probably going to get slaughtered for this, but I think a good example is the first edition of the Perl camel book. It was trying to be way, WAY, too cute. I like Larry Wall, and it wasn't all bad, but it seemed like he was trying too hard to be funny, and trying not hard enough to be well organized, clear and concise. Sometimes I found it really tiresome to wade through some if it when I was just looking for a nugget of information. Also, I think it made some of the examples harder to understand because he was more concerned with fitting an example into a joke rather than giving me a useful, practical example.
I've noted that the newest edition has toned down the "stand-up" quite a bit, while still preserving a sense of personality.
--
Re:Womyn and Linux (Score:2)
The fact that you've identified 4 well-known OSS programmers who are male doesn't mean OSS is a patriarchal system that fears women. It's probably indicative of social training that starts conditioning females away from hard science at an early age. Blame our social structure, not OSS. If I were to be an over-analytical dork, I could even make the claim that OSS is an inherantly "feminine" movement, if we assume that Communication and Cooperation is a feminine attribute, as opposed to hardass competition being a masculine attribute.
That characterization of programming languages as being masculine or feminine is really fucking retarded. People generally are going to use a programming language for a purpose for which it's well suited. If you're writing an OS or device driver where speed is essential, are you going to write it in freakin' SMALLTALK? Jesus. I'll also point out that Lisp and Smalltalk are used a lot in academic settings, primarily by MALE researchers.
Then you go on to blather about slashdot geeks talking about capitalism as being the way to market linux vs some socialism-related crap. Actually, i'll point out AGAIN that open source and free software is a pretty socialist movement; it's certainly NOT based on a capitalist agenda. However, trying to get commercialware companies to port to Linux may be focusing on the capitalistic tendencies of people, but how ELSE are you going to get broad acceptance? People may be more forgiving of current weaknesses based on the "free" concept, but to get long-term acceptance they're going to have be able to run commercial apps.
And how would you suppose we "break through the gender gap?" Affirmative action in kernel hacking? Sheeeit. If a woman wants to contribute to free software, I really do NOT think anyone's going to stop her. Hell, if we're all as geeky and pathetic as you imply, then wouldn't we welcome any and all female contributions?
Take Deb's gender out of the discussion (Score:2)
It plainly is not appropriate to ask Deb about her linuxchix.org website in this forum.
Clearly, there are gender issues that do need to looked at (introducing young girls to computing, etc.), but screaming about it in an unrelated discussion WEAKENS THE MESSAGE. And before you scream at me, dearies, I have been on the front lines for a while and have seen quite a bit of the action.
Just because there is a female-centric linux website out there does not mean those women who contribute to it are cutting themselves off from the rest of the linux community. And about a "woman centered linux distribution", where the heck was that even mentioned? Deb was talking about better documentation NOT a new distribution.
How to motivate open-source doc writers (Score:3)
From the article itself:
Here's a serious one: Cut the documentation writers in on the stock offerings at the IPO's. Consider putting good documentation people on the corporate boards. If Deb had been given the same stock in LNUX as Eric Raymond had, she'd be able to devote herself to Open Source documentation full-time. If people saw the possibility of a serious return on their investment of time (even if it was not unlike a lottery-level chance of a payoff), this would motivate a great many. Also, spread the benefits more widely. People should be able to get a share or a couple shares for writing a page. Perhaps this would require an investment-club style of operation, but if you could get $50 or $300 for a couple evenings of work on a page, people would find it worthwhile.Re:Dissapointing... (Score:3)
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.
Also note, that question was the only question moderated up to 5, people wanted it answered, and she skirted by it by claiming it too "political"? Is she running for office or something?
-- iCEBaLM
Needs to be said again (Score:3)
I don't know how many million times I've read "I'd do it but I don't program/I've only had 1 semester of Java/I'm not a good programmer/etc. Well, tattoo Roblimo's advice on your forehead! There's more than one way to contribute or give back!
Re:Covering the bases (long) (Score:4)
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.
Well... html pages are neat for docs... though I *hate* having to jump through more than one or two links to get anything - any of those howtos online that are split up by section are horribly frustrating. What is this - three or four paragraphs, then I have to click again... I can't scan back and forth. Usually there is a 'one big html file' option, but often there isn't. That's not good help, separating for the sake of separating. HTML also doesn't work well in a CLI/shell env... I suppose that man could call lynx instead of less (or whatever you may have it set to), but man pages shouldn't be split up, and often, getting X, the browser and the internet link are the areas where one would need the man page the most.
There still needs to be man in its current incarnation... just updated. (see several other comments from various ppl about how the *BSD, AIX, and Solaris man pages are better).
Dissapointing... (Score:5)
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
Covering the bases (long) (Score:5)
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.