[wiki] Documentation: "Clearly beneficial to many users"

billdale · 2005-10-27 17:21:49

I just sent the following note to the people working on GIMP (www.gimp.org) and thought I’d include it here because it seems to do a pretty good job of summing up something I’ve been experiencing for a couple of years now…

“Just wanted to drop you (and William Skaggs, Ćedric Gémy, Julien Hardelin, Raymond Ostertag, Mel Boyce, Daniel Egger, Róman Joost, Oliver Ellis, Jakub Steiner, Róman Joost, Daniel Egger, Sven Neumann, Michael Natterer, Henrik Brix Andersen, Daniel Egger, Thomas Schraitle, Chris Hübsch, Axel Wernicke, Domingo Stephan, Zhong Yaotang, Róman Joost, and Daniel Egger — the documentation team), a note to tell you how much I appreciate the excellent, solid, in-depth set of directions that come with GIMP.

“I won’t go into the boring details (obviously everyone one your end is aware), but the long and short is that from my perspective (a simple end user), if there’s one gigantic stumbling block in the (enlightened) world of open source software, it’s ratty documentation. I may be wrong, but I (strongly) suspect the lack of comprensive comprehendable “How to use this” guidance is preventing millions of people from taking advantage of some genuinely wonderful programs and systems that are freely available.

“I’m genuinely glad to say that GIMP is not one of them.”

~ ~ ~ ~ ~ ~ ~ ~ ~ ~

As it says at the top of the GIMP site, “The GIMP is the GNU Image Manipulation Program. It is a freely distributed piece of software for such tasks as photo retouching, image composition and image authoring.”

I’ve been using Photoshop forever, but because of odd circumstances found myself without access to it and in need of a decent graphics package. I did a quick search on “Photoshop replacement”+open+source and an hour or two later (dial-up), had downloaded, installed and opened the program. Even though the tools, menu and interface are similar to Photoshop they aren’t the same, so, naturally, I was a little foggy on how to use it. So I pressed the F1 key.

Wow.

I won’t beat the lame horse or repeat myself (too much), but I can’t tell you how convinced I am of what it says in the second paragraph of the note I just sent to GIMP: As boring, mundane and difficult as it is to produce good documentation for site admistrators and the “Ultimate End User” (people who know nothing about coding, html, css, or much more than how to send an email or use a browser), it will, I believe, prove critically important to the long-term success and widespread use of any open source effort.

Although I know a little (and I mean a little) about coding, html, css, etc., I’m much closer to end user status and if there’s one thing that makes me reluctant to download, install and start using an application like Textpattern (or Mambo or Joomla or You Name It), it’s my experience with the long hours, days, weeks of mostly trial and error struggling (and forum browsing and searching) and frustration that seems to be nearly universal standard operating procedure with open source software… And not only that, it seems to be almost as universally accepted by the creators of that software as “just the way it is.” It seems that while there is enormous focus, energy, talent, skill and creativity applied to the (genuinely brilliant) software itself, end user documentation almost always gets the “annoying poor relative” short end of the stick.

And that’s understandable, I suppose: Those most interested in open source (for the subtle as well as technical reasons), are people who are excellent code writers and dedicated collaborators working hard to translate someone’s, or some group of people’s, vision into working reality. And that’s a big job. And, of course, most people who write code – software engineers – simply aren’t interested in writing documentation (probably for the same reason alpine skiers wouldn’t be interested in writing “How to ski in the Alps” tutorials – they’d rather just do it).

Anyway… So as not to be “one of those people who just complains,” the two best examples of comprehensive open source documentation I’m aware of are the PhpBB Userguide (http://www.phpbb.com/support/guide/) and, suddenly, the Help system that is part of the GIMP download (they also have some nice tutorials online at http://www.gimp.org/tutorials/).

I don’t know much about GIMP (just came across it yesterday), but I know PhpBB is one of the most widely used pieces of open source software around. The most important reason for that is because it’s a decent forum system. But it may also have something to do with the documentation making it possible for just about anyone to use it.

The Textbook project is a good start. The people who’ve been working on that have done a nice job on what’s there. More is needed. More in Textbook and more in the way of simple, clear, thorough tutorials. From what I can tell, Textpatten is one of the finest pieces of open source cms software available (everyone seems to be doing fantastic work). It looks like it DESERVES “proper” documenting. I may be all wet, but I’m pretty sure devoting whatever resources are required to accomplishing that would lead to nothing but more and more people using it (and more and more people deciding to house their textprojects at Textdrive?).

And to anyone thinking of replying to this with the standard, “Hey… Good idea… Why don’t you get busy, pitch-in and help it happen,” please don’t. It makes no sense to encourage confused people who don’t know anything about how the system works to contribute to documentation. And, if you ask me, telling people who ask for better documentation to do that is always a “cop out.” We see it every time anyone raises this issue in ANY open source project forum. If people like me knew enough about Textpattern to document it we wouldn’t be typing things like this.

Now… Having said all that I want to say that even though it may seem like I’ve got a bone to pick or axe to grind with Textpattern, I don’t. I like it a lot. I’ve downloaded it, have made my way through most of the Textbook, fished around this forum, looked elsewhere, etc., and done some of the “coming to grips” it takes. But I’m still puzzled and, most importantly, still reluctant to “make a commitment to it.” Not because I don’t think it’s an incredible piece of work, and not because I don’t think it would do what I’d need it to do. No. I’m reluctant because even though I’m pretty sure I could figure it out and cope with it, I can tell that the way things are right now (documentation/comprehension-wise), it will continue to be a struggle.

And, maybe more importantly, when it comes to a lack of excellent documentation, I’m extra reluctant when it comes to OTHER people I’d invite to use the system, were I to continue on to the point it was fully operational. Other people who know even less than I about things like code, html, css, etc. People who don’t know (and don’t want to know), much more about internet communications than email and browsers. People I’d like to have participate, contribute, etc.. And, if not those people, who is a content management system for? Although interesting, I don’t really need a cms to create sections, logically ordered web pages and a site map. As I understand it, the primary purpose of a cms is to make it easier and more efficient for groups of people to use the internet to communicate. I could have the best cms in the world sitting on my hard drive or server right now but if it’s not possible for those other people to learn and understand how to use it (without having to make their way through an internal briar patch), what good will it do us?

ubernostrum · 2005-10-27 22:37:43

Um.

Could we get the abstract for this article?

zem · 2005-10-27 23:03:00

And to anyone thinking of replying to this with the standard, “Hey… Good idea… Why don’t you get busy, pitch-in and help it happen,” please don’t. It makes no sense to encourage confused people who don’t know anything about how the system works to contribute to documentation. And, if you ask me, telling people who ask for better documentation to do that is always a “cop out.” We see it every time anyone raises this issue in ANY open source project forum. If people like me knew enough about Textpattern to document it we wouldn’t be typing things like this.

There’s a reason this is the standard answer in any open source project. Open source is a community effort. Nothing gets done until somebody does it.

You can rail all you like about the unfairness of that, but it won’t change the fact that you’re asking someone to do a difficult and unrewarding job for free.

The reason developers don’t write (much) documentation is the same reason that technical writers don’t code: we’re not very good at it. It’s taken a lot of time and effort to produce the documentation we have. It would take a lot less time for a tech writer to learn the Textpattern ropes, than for the developers to learn technical writing.

I could have the best cms in the world sitting on my hard drive or server right now but if it’s not possible for those other people to learn and understand how to use it (without having to make their way through an internal briar patch), what good will it do us?

The “it’ll bring in more users” argument is also a cop out. We could have millions of users, but what good would that do us? Open source projects are driven by supply, not demand.

So, supply something. Either learn Textpattern, and write some documentation yourself; or hire someone else to do it for you.

Mary · 2005-10-27 23:07:13

You need to understand: you came off sounding quite rude, and like a classic “troll”: someone with 1 post shows up to create that 1 post, to explain to us all what we should be doing that we’re not, including a sermonette complete with “don’t answer if your answer is this”.

I’ve spent literally hours and hours – that’s not an exaggeration – working on the documentation alone, and I am not a major contributor to it. That’s aside from creating and documenting plugins, reporting bugs, submitting patches and helping out at the forum the best I can, as well as still managing to personally respond to all my email. Oh yeah, and sometimes I pretend that I have a life.

It is unfair for you to come seemingly blazing in here and elaborating on perceived failings when you don’t have a clue all the people actively involved, or how long and hard they spend at it. That’s outside judging motives, which is completely unacceptable here. This isn’t GIMP, phpBB, Mambo, or anything else under the sun. I would never suggest that these people I work alongside with aren’t doing it for nothing, their best, and doing a damn fine job of it too, and quite frankly, like it or not, I’m in a better position to do that than you.

I’ll assume in your favour, for the moment, that you’re not what you sound like so I won’t lock the thread yet. I’ve moved this topic to Textpatter where it belongs. How about telling us what you can do to help?

marco · 2005-10-27 23:25:02

At the very least, instead of venting your frustration in the forum, you could have posted questions about the things that give you a hard time with the software. From what I’ve seen so far, it is pretty likely that you’d have gotten some answers, or someone would have tried to help you out.

Jeremie · 2005-10-27 23:38:59

mary wrote:
How about telling us what you can do to help?

I can make damn good pasta… will that help ? ;->

Last edited by Jeremie (2005-10-27 23:39:12)

billdale · 2005-10-28 03:19:06

See what I mean? Troll, no-goodnick, attacker, etc.. Come on. Take it easy on the flames, willya?

Favorite response (so far): Pasta ;->.

But really (“and in all seriousness”), thanks for your responses. I agree with you all, except I’m really not a troll, don’t mean to be rude, and really do appreciate the elegant result of the work everyone’s done on Textpattern to this point, including the existing documentation. It sounds like a cliché, but it’s one of those cases in which the (maybe!) sincere character says, “I wouldn’t have said what I said if I didn’t care.”

If I sounded like I was ranting, I didn’t mean it that way. Or, if I was, I didn’t mean to “take it all out” on Textpattern. From what I can tell, Textpattern is one of the best open source programs around. From what I can tell, it really IS a brilliant “piece of work,” and far be it from me to criticize ANYone involved with contributing to it (including the existing documentation)… That wasn’t the point (at all). What I was referring to is something I’ve seen in nearly every instance of open source software I’ve encountered (starting with openacs.org), and I really do believe it’s a major stumbling block when it comes to making it possible for larger numbers of (almost everyday) people to take advantage of the great things the open source community has to offer.

It’s a tough problem. I appreciate what zem had to say about developers and technical writers. And I even appreciate (almost) the comments about putting my money where my mouth is. But that’s what makes it a tough problem and a catch-22… I’m not a technical writer either. I’m clueless as to the ins and outs of creating good (or even passable) documentation, and not having complete and clear documentation (although what exists is good), makes it difficult for me to know or do enough to be useful (to not just jot down or make up ad-hoc things or reinvent the wheel).

But, believe it or not, I’m not really all that concerned about me. I can figure it out. It’s those Other People I mentioned. Zem also asked what good millions of users would do. Interesting question. I’m not sure about the answer, but I imagine it would have something to do with millions of people being able to take advantage of an excellent thing without having to spend US $29.95/month or 2,900 dollars on whatever cms Microsoft or Cosmodemonic Telephone and Telegraph makes available. (Isn’t that sort of The Point of open source?)

One of the things is “I’m a believer” in what I perceive to be the “bigger thing” everyone who works so hard (and well) on things like Textpattern seems to believe in. I said what I said because I believe it’s a major impediment to the widerspread success of the open source “genre.” And in the, “Please, don’t get me wrong!” category, I probably should’ve been a little clearer on the point that Textpattern’s documentation to this point is as good as, and maybe better than, most, and that the issue I was ranting about (if that’s what I was doing), was much more about the state of open source documentation in general (but which Textpattern is not immune to).

As to the “Can we get the abstract on this?” idea, I had to laugh. Again, I agree (sorry for yacking so much – just be glad I’ve only put two posts in here). I guess the soundbite headline would be something like, “So okay… Where does one locate some willing technical writers cuz if that’s what it takes they should be here or the only people who’ll ever use this great little thing are the people in the community and while that would probably be fine I can’t quite believe that’s the point.”

No offense to anyone intended. As Mary pointed out, I don’t know any of you any better than you know me, but from what I can tell you’re all doing all you can to create the best possible thing you can and it seems to be working. It shows. Keep it up, and if you find this a pain in the arse please don’t pay it any attention or let it influence you negatively. That really isn’t the point. You’re doing the right thing and you’re doing it well.

As to what I can do, who knows? Documentation? Where’s the documentation hub? Who’s leading the way? What’s the plan, the outline, the nuts and bolts of the wheel? I don’t know anything (substantial), but again, who knows?

Mary · 2005-10-28 03:52:20

That’s not a flame, that’s an observation. This has all been said and covered before, and you could easily have asked before waxing eloquent if you looked but really couldn’t find anything on the subject, or if you could but didn’t understand what you found. No one is hiding anything (‘cept maybe Dean, he’s sneaky, oh and I have a tendancy to throw balled up socks at people and then hide…), its all public, easy to find.

Stickied: TextBook notes
TextBook main page

That’s like showing up while someone is finishing pouring the concrete for a house foundation and saying (in over 1000 words), “You need walls. Why don’t you have walls? Do you not know you need walls?…” I don’t think I need explain how that would be received, right?

:)

zem · 2005-10-28 03:54:23

(Isn’t that sort of The Point of open source?)

No. You’re basing your argument on flawed assumptions.

People don’t contribute to open source projects to Stick It To The Man, or because they subsist on Fame and Good Vibes, or because they want to be A Part of Something Bigger. (Yep, people have written entire books about those reasons. You’ll notice that those people spend their time writing books, not code)

People contribute to open source projects because they use the software, and it suits them to make it better. Casual contributors and the core dev team alike all write code (and documentation, and translations, and templates) first and foremost for their own projects. We write code because we need it ourselves, or because people pay us to, one way or another. We don’t publish that code because it makes us Feel Good, or because ethics or ideology require it. We publish code because it’s an efficient way of testing it, and because other people might fix bugs and make it better, and because it makes it easier to finish one thing and move on to the next.

A dozen users or a million makes no difference. Demand isn’t part of the equation. (In fact, having too many users can and does destroy projects, by spreading the available supply of resources too thin).

Yeah, Fame and Reputation are somewhere on the list of motivating factors, but they’re pretty low down. Somewhere between ‘if I don’t do this now, I’ll forget’, and ‘publishing code is easier than backing it up’.

In short, The Point of open source is that it makes a bunch of stuff easier. That’s all. It’s a way of writing software, not a march to change the world.

PS, don’t take this as a flame, or a fight to the death. Just an observation, as Mary said. Not much gets done around here by engaging in debates, forming committees, or expecting people to rally in response to a stirring speech.

Last edited by zem (2005-10-28 04:21:12)

aesop1 · 2005-10-28 05:12:32

Well, although I’m not in agreement with BillDale on this, I do appreciate that he at least placed his rant in the “textpatter” area.

It would have been really annoying to read this in “Feature Requests,” “How Do I” or worse yet, “Plugins.”

Ubernostrum cracked me up with the abstract request and Jeremie as well with his pasta-making quip. Good stuff — or maybe I really just need to get out more.

Last edited by aesop1 (2005-10-28 05:15:05)

maniqui · 2005-10-28 05:38:34

Few weeks ago, I felt a similar feeling of frustration, similar to the frustration that billdale post above.

In that time, I was trying to learn how to use Drupal.

I already was in love with TXP (true eternal love since 2004-10-10) but I wanted to learn another CMS, just in case, because some clients would prefer it (specially for the integrated forum), and also I wanted to try Drupal, find out what Drupal was.

I spent many hours reading, testing, learning, failing, testing, reading, lot of Firefox windows, each one plenty full of tabs, trying to read and learn from lot of resources at the same time, and at the same time, testing and failing, and sometimes also having success.
Three weeks of pain and frustration. Really, I think I tried it and must admit I failed.

Finally, <a href=“http://drupal.org/node/34007”>I gave up. Drupal wasnt for me</a>. This is a link to a thread in the Drupal forums where I explained my painful experience with Drupal, trying to be constructive with my critics to Drupal. It is easy to read, and I also talked a bit about TXP in the final sentences.
I received a lot of feedback from Drupal users, with ideas very similar to those that Zem and Mary posted above in this thread.

Now, I felt shame, because before posting that in Drupal forum, I had asked just one question in Drupal forums. :S (well, one more than billdale, that posted 0 questions before this thread :D )

I think frustation also came because I didnt feel like I wanted to be part of Drupal community. I dont know why.

Also, in my mind, I was all the time comparing Drupal with TXP, and blaspheming myself (and Drupal) because my incapacity to get the logic behind Drupal.
It was very hard to make “insights” in the understanding of Drupal.

The truth is that the most useful information and documentation about Drupal, I didnt find it at Drupal site or Drupal forums. I founded it at <a href=“http://bryght.com/”>Bryght</a>.
Drupal is older than TXP and its documentation is really a mess. Headaches!

After three weeks of pure frustration, I decided to come back to the warm arms of TXP :D
I posted a thread (<a href=“http://forum.textpattern.com/viewtopic.php?id=12001”>TXP sí, Drupal no!</a>) in the spanish forum of TXP.
I received some feedback from <a href=“http://forum.textpattern.com/profile.php?id=734”>nardo</a>, and he gave me this words:
Horses for courses.

Sometimes, with each piece of software (and particulary with open-source software and the communities behind) you have to fall in love, not always from the begining of the relation.
Not every software out there is for everyone.

I just wanted to say that I can understand billdale’s feelings and points.
Billdale, I can say to you what people in drupal forums said to me: I hope you give Drupal another try.
So, I hope you give TXP another try, if you feel like it deserves the effort.

Finally, I suggest you billdale that you should read http://moae.org/txp/ (if you didnt read it already).
It was one of my firsts approach when trying to have “insights” with the logic behind TXP.

Thanks <small>and please excuse my poor english in this post</small>.

Last edited by maniqui (2005-10-28 05:46:26)

Mary · 2005-10-28 06:05:53

aesop: this was a feature request, I moved it here…

Textpattern CMS

Textpattern CMS support forum

#1 2005-10-27 17:21:49

[wiki] Documentation: "Clearly beneficial to many users"

#2 2005-10-27 22:37:43

Re: [wiki] Documentation: "Clearly beneficial to many users"

#3 2005-10-27 23:03:00

Re: [wiki] Documentation: "Clearly beneficial to many users"

#4 2005-10-27 23:07:13

Re: [wiki] Documentation: "Clearly beneficial to many users"

#5 2005-10-27 23:25:02

Re: [wiki] Documentation: "Clearly beneficial to many users"

#6 2005-10-27 23:38:59

Re: [wiki] Documentation: "Clearly beneficial to many users"

#7 2005-10-28 03:19:06

Re: [wiki] Documentation: "Clearly beneficial to many users"

#8 2005-10-28 03:52:20

Re: [wiki] Documentation: "Clearly beneficial to many users"

#9 2005-10-28 03:54:23

Re: [wiki] Documentation: "Clearly beneficial to many users"

#10 2005-10-28 05:12:32

Re: [wiki] Documentation: "Clearly beneficial to many users"

#11 2005-10-28 05:38:34

Re: [wiki] Documentation: "Clearly beneficial to many users"

#12 2005-10-28 06:05:53

Re: [wiki] Documentation: "Clearly beneficial to many users"

Board footer