Documentation Dearth Dooms Open Source Projects

[abarbarian]

Dan Allen and Sarah White: (2015)

 

 

 

One of the essential draws to open source software should be superior product documentation. Well-written user guidelines are a key strategy that software developers should use to increase an open source project's growth and user adoption.

All too often, programmers finish their last line of code and shove the open source software out the door -- or, more realistically, post it on their website waiting for users to flock to its greatness. Documentation is often an afterthought -- or the software developer does not think about it at all.

A pair of open source entrepreneurs are determined to help software developers solve the problem of poorly done or missing documentation. Dan Allen and Sarah White are coleads of the Asciidoctor Project and cofounders of OpenDevise. Allen is a software developer and community catalyst; White works on the documentation for the Asciidoctor project.

 

Any one who helps to get better documentation for open source projects deserves a medal.

[V.T. Eric Layton]

I wish I had more time and inclination to help out in that area, but sadly... I'm a lazy bastid by nature.

[Robert]

One of the reasons I stick with Ubuntu is almost every problem can be solved with a google search.

[abarbarian]

One of the reasons I stick with Ubuntu is almost every problem can be solved with a google search.

 

Searching is so so wearisome, that is why I chose Arch as you only have to go to the wiki for 99.9% of any query's. Apparently the wiki is so thorough that folks using other os's use it aswell.

[abarbarian]

The job is not done until the documentation is complete

 

 

Which came first, the program or the documentation? Therein lies the dilemma.

I don't think I have ever heard anyone say, "This documentation is great." Mostly I hear how badly some specific documentation sucks, and I have repeated that refrain myself many times.

 

RTFM? How to write a manual worth reading

 

The title of this essay comes from Kathy Sierra, who in a presentation years ago had a slide that said, "If you want them to RTFM, make a better FM." But how do we go about doing that?

 

Two more articles about documentation both a nice read.

[Guest LilBambi]

So true!

[Guest LilBambi]

It is awesome when great document/manual creating people join up with great program writing people.

The great programmer needs to be able to get at least the basics out there for the doumenters can make the documentation readable, understandable, even interesting.

I have read some great documentation over the years, but mainly for some simpler programs. The more indepth the program, the more complicated the documentation.

My Jim could decipher it if he was really interested in the program. But sometimes my eyes would glaze over trying to understand some of those instructions. I would be right on the edge of understanding or even have it for a second, but there would be parts that would elude me or confuse me. Thankfully I had Jim to help.

But it shouldn't be that mind numbing to learn a program.

Despite how poorly written, I could still understand it with many programs. But there were times and it seemed that a translator translated words but not the true meaning of those words. They could be taken multiple ways and in conjunction with other poorly translated sections, it would leave me reeling trying to decipher it.

Jim on the other hand, grew up deciphering poorly translated hardware manuals as an electronics technician, and he just had a gift to be able to decipher the hardest manual.

I do not think it should take a genius level brain to understand a manual/documentation. I am considered intelligent - my IQ is considered above average or bright/brilliant level depending on whose chart you use, but I am no genius.

As I say, less intense programs, I can easily decipher on my own, others I needed Jim's genius to decipher at least certain parts for me. He truly had the teacher's gift! He couLd take even the most complex subject and bring it down to true understanding for most people. As I say, it was his teacher's heart.

[abarbarian]

but I am no genius.

 

Kudly koalas don't need to be geniuses.

[Guest LilBambi]

Thanks!

 

Jim and Bruno were very similar in that way. But Bruno did it via the forums, and Jim just did it one on one. Folks that frequented our CNIRadio.com chat quickly found that out.

[securitybreach]

Thanks!

 

Jim and Bruno were very similar in that way. But Bruno did it via the forums, and Jim just did it one on one. Folks that frequented our CNIRadio.com chat quickly found that out.

 

Indeed Fran