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.
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]:
make our site easier for you to use.
We do also share that information with third parties for
advertising & analytics.
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.
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.
Uber and Lyft are destroying Austin's driver-friendly rideshare economy
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.
Got two minutes to spare? We'd love to know a bit more about our readers.
All data collected in the survey is anonymous.
-- submitted from IRC