Jump to content


Documentation Dearth Dooms Open Source Projects

linux open source documentation

  • Please log in to reply
9 replies to this topic

#1 OFFLINE   abarbarian

abarbarian

    Thread Kahuna

  • Forum MVP
  • 5,633 posts

Posted 18 June 2015 - 09:03 AM

Dan Allen and Sarah White: (2015)



Quote

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:
Install ARCH
You'll never need to install it again
"I did and I'm really happy"

Posted Image~~~~~~~~~~~~~Posted Image

#2 OFFLINE   V.T. Eric Layton

V.T. Eric Layton

    Nocturnal Slacker

  • Forum Admins
  • 21,517 posts

Posted 18 June 2015 - 04:41 PM

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

#3 OFFLINE   Robert

Robert

    Message Mogul

  • Members
  • PipPipPipPipPip
  • 340 posts

Posted 18 June 2015 - 11:57 PM

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

#4 OFFLINE   abarbarian

abarbarian

    Thread Kahuna

  • Forum MVP
  • 5,633 posts

Posted 19 June 2015 - 09:43 AM

View PostRobert, on 18 June 2015 - 11:57 PM, said:

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:
Install ARCH
You'll never need to install it again
"I did and I'm really happy"

Posted Image~~~~~~~~~~~~~Posted Image

#5 OFFLINE   abarbarian

abarbarian

    Thread Kahuna

  • Forum MVP
  • 5,633 posts

Posted 30 June 2015 - 07:08 AM

The job is not done until the documentation is complete


Quote

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

Quote

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:
Install ARCH
You'll never need to install it again
"I did and I'm really happy"

Posted Image~~~~~~~~~~~~~Posted Image

#6 OFFLINE   LilBambi

LilBambi

    Australisches Googler

  • Forum Admins
  • 22,545 posts

Posted 30 June 2015 - 07:27 AM

So true!
Bambi
AKA Fran

Posted Image
My Public Key for Email :: BambisMusings Blog :: Fran's Computer Services Blog :: MyPassionIsBooks Blog :: 5BuckReview :: CNIRadio
"The Net interprets censorship as damage and routes around it." ~John Gilmore (Time Magazine, Dec 6, 1993)

#7 OFFLINE   LilBambi

LilBambi

    Australisches Googler

  • Forum Admins
  • 22,545 posts

Posted 30 June 2015 - 07:43 AM

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.
Bambi
AKA Fran

Posted Image
My Public Key for Email :: BambisMusings Blog :: Fran's Computer Services Blog :: MyPassionIsBooks Blog :: 5BuckReview :: CNIRadio
"The Net interprets censorship as damage and routes around it." ~John Gilmore (Time Magazine, Dec 6, 1993)

#8 OFFLINE   abarbarian

abarbarian

    Thread Kahuna

  • Forum MVP
  • 5,633 posts

Posted 30 June 2015 - 08:59 AM

Quote

but I am no genius.

Kudly koalas don't need to be geniuses. :hug:
Install ARCH
You'll never need to install it again
"I did and I'm really happy"

Posted Image~~~~~~~~~~~~~Posted Image

#9 OFFLINE   LilBambi

LilBambi

    Australisches Googler

  • Forum Admins
  • 22,545 posts

Posted 30 June 2015 - 01:14 PM

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.
Bambi
AKA Fran

Posted Image
My Public Key for Email :: BambisMusings Blog :: Fran's Computer Services Blog :: MyPassionIsBooks Blog :: 5BuckReview :: CNIRadio
"The Net interprets censorship as damage and routes around it." ~John Gilmore (Time Magazine, Dec 6, 1993)

#10 OFFLINE   securitybreach

securitybreach

    CLI Phreak

  • Forum Admins
  • 23,942 posts

Posted 01 July 2015 - 12:35 PM

View PostLilBambi, on 30 June 2015 - 01:14 PM, said:

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:
Posted ImagePosted Image Posted Image
CNI Radio/G+ Profile/Configs/PGP Key/comhack π

"Do you begin to see, then, what kind of world we are creating? It is the exact opposite of the stupid hedonistic Utopias that the old reformers imagined. A world of fear and treachery and torment, a world of trampling and being trampled upon, a world which will grow not less but more merciless as it refines itself. Progress in our world will be progress toward more pain." -George Orwell, 1984





Also tagged with one or more of these keywords: linux, open source, documentation

0 user(s) are reading this topic

0 members, 0 guests, 0 anonymous users