Jump to content
abarbarian

Documentation Dearth Dooms Open Source Projects

Recommended Posts

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. :Laie_95:

  • Like 3

Share this post


Link to post
Share on other sites
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. :(

  • Like 1

Share this post


Link to post
Share on other sites
Robert

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

Share this post


Link to post
Share on other sites
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. :whistling:

  • Like 1

Share this post


Link to post
Share on other sites
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. :breakfast:

  • Like 1

Share this post


Link to post
Share on other sites
LilBambi

So true!

Share this post


Link to post
Share on other sites
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.

  • Like 1

Share this post


Link to post
Share on other sites
abarbarian
but I am no genius.

 

Kudly koalas don't need to be geniuses. :hug:

  • Like 1

Share this post


Link to post
Share on other sites
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.

  • Like 1

Share this post


Link to post
Share on other sites
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 :thumbup:

  • Like 1

Share this post


Link to post
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now

×
×
  • Create New...