SoylentNews

"exec" writes:

Story automatically generated by StoryBot Version 0.2.2 rel Testing.
Storybot ('Arthur T Knackerbracket') has been converted to Python3

Note: This is the complete story and will need further editing. It may also be covered
by Copyright and thus should be acknowledged and quoted rather than printed in its entirety.

FeedSource: [HackerNews]

Time: 2017-06-02 17:29:27 UTC

Original URL: https://thenextweb.com/dd/2017/06/02/free-software-is-suffering-because-coders-dont-know-how-to-write-documentation/?utm_source=social&utm_medium=feed&utm_campaign=profeed#.tnw_IZruvbiT [thenextweb.com] using UTF-8 encoding.

Title: Free software is suffering because coders don’t know how to write documentation

--- --- --- --- --- --- --- Entire Story Below --- --- --- --- --- --- ---

Free software is suffering because coders don’t know how to write documentation

Arthur T Knackerbracket has found the following story [thenextweb.com]:

                                                        TNW uses cookies to personalize content and ads to
                                                        make our site easier for you to use.
                                                        We do also share that information with third parties for
                                                        advertising & analytics.
                                               

                        by Matthew Hughes [thenextweb.com]
                        —
                                                in Design & Dev [thenextweb.com]
                                       

The Open Source Survey asked a broad array of questions. One that caught my eye was about problems people encounter when working with, or contributing to, open source projects. An incredible 93 percent of people reported being frustrated with “incomplete or confusing documentation�.

That’s hardly a surprise. There are a lot of projects on Github with the sparsest of descriptions, and scant instruction on how to use them. If you aren’t clever enough to figure it out for yourself, tough.

That’s unfortunate. People don’t quite realize how vital documentation is to the success of a project.

We’ve been known to tell a developer “If it isn’t documented, it doesn’t exist.� Not only does it have to be doc’d, but it was to be explained and taught and demonstrated. Do that, and people will be excited — not about your documentation, but about your product.

I came across another brilliant quote about documentation from Stack Overflow founder Jeff Attwood’s blog [codinghorror.com], this time by JavaScript developer Nicholas Zakas [twitter.com].

But beyond the practical reasons for documentation, there’s also the argument that it builds a sense of community. Not only do you know who your fellow collaborators are, and what they’ve accomplished, there’s also a clearly-defined sense of mission and purpose.

Here’s how the Open Source Survey explained it (emphasis theirs):

According to the Github Open Source Survey, 60 percent of contributors rarely or never contribute to documentation. And that’s fine.

Documenting software is extremely difficult. People go to university to learn to become technical writers, spending thousands of dollars, and several years of their life. It’s not really reasonable to expect every developer to know how to do it, and do it well.

And then there’s the fact that twenty-five percent of open source contributors say they read and write English less than “very well.�

But there’s a golden opportunity here. I’d love to see the thought leaders in the industry — Google and Github, if I have to point a finger — step up.

Google just launched a free online course [thenextweb.com], trying to tempt language experts to become localizers. Why can’t it do the same for writers, in order to teach them the skills required to write about software?

Similarly, GitHub could launch a course aimed at introducing writers with no previous software development experience to Git.

Not only would this help solve the documentation drought, but it would also be a loud demonstration that you don’t have to be a developer to contribute to open source.

        Read next:
       
                Uber and Lyft are destroying Austin's driver-friendly rideshare economy

                        Matthew Hughes [thenextweb.com]
                                                        is a reporter from Liverpool.
                                                        Happy to hear your thoughts
                                on matthughes@thenextweb.com [mailto] or
                                @matthewhughes [twitter.com] on Twitter.
                                       

                        Matthew Hughes is a journalist from Liverpool, England. His interests include security, startups, food, and storytelling. Follow him on Twitter [twitter.com].

Here's some more distraction

Stay tuned with our weekly recap of what’s hot & cool by our CEO Boris [soylentnews.org].

                Join over 260,000 subscribers!
       

                                Sit back and let the hottest tech news come to you by the magic of electronic mail.
                       

                                Prefer to get the news as it happens? Follow us on social media.
                       

                                                        1.76M followers
                                               

                                                        1M likes
                                               

                                Got two minutes to spare? We'd love to know a bit more about our readers.

                                Start! [soylentnews.org]
                       

                                All data collected in the survey is anonymous.
                       

-- submitted from IRC

Original Submission