SoylentNews is people
SoylentNews
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.
[...] 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.
-- submitted from IRC
(Score: 5, Interesting) by VLM on Monday June 05 2017, @01:03PM (2 children)
And whats the literacy level of the target population?
I know the literacy level of the "hacker" "techie" community is enormously higher than the normie community but its still not that high.
Anecdotally I remember cracking open my first electrodynamics textbook at uni I donno maybe it was some old edition of Griffiths, whatever, I can assure you it seemed "incomplete or confusing documentation" of how the universe works. Yet with some study I passed the class... You want to do crazy high level wizardry, well the spellbook for that is naturally going to look a little mysterious to the first time viewing apprentice. Maybe, if you don't know what a primary domain controller is, you shouldn't be setting on up on the prod network at work. Maybe if you don't know what BGP is, you shouldn't be in charge of configuring the router that connects to 4 upstream ISPs.
Note that people who are operating at the correct level will not be served by scrapping the higher level spellbooks and replacing everything with "see spot run" level stuff. Thats the classic Linux desktop environment mistake. I don't want to use a Linux designed for people who barely know how a mouse works, any more than a master craftsman fine finish carpentry expert wants to use a plastic pink "hello kitty" hammer instead of pro tools.
Anyway there's two other comments. If you want to understand electromagnetism and all that, there's the classic text "Div, Grad, Curl, and All That: An Informal Text on Vector Calculus" which is kinda a pre-req no matter if you know it or not. And there's books like the ARRL handbook and numerous other ham radio texts which will give you a sort-math-free education about RF which will help a lot when you're learning the math. Just saying if you've never taught yourself anything, there are probably dozens if not thousands of sources so if you're reading a particularly bad source, try another source.
I'm reading a sci fi book called ninefox gambit but in the mostly non-fiction category I'm reading "Dispatches" by Mike Herr which is the autobiography of a boomer "journalist" who covers the Vietnam War while basically being high all the time. its kinda like Hunter S Thompson goes to the Vietnam War as a correspondent instead of joining the Hells Angels. Dispatches was written about ten years after Hells Angels and there is some resonance. Anyway as a Vietnam War documentary its shit compared to a book like "Fire in the Lake" its totally "incomplete or confusing documentation". Yet it still serves its purpose. If you want a documentary, and pick up something else, that doesn't mean its a shit book or you're illiterate, it just means you're really bad at selecting books for a given topic. If your book sucks at task "X" then ask someone what book to read for task "X". Or a more concrete example lets say you hate fantasy and love sci fi and someone trolls you into reading the LOTR trilogy, you're gonna hate it, and that doesn't mean the book sux or that you can't read, but it does mean you can either get trolled or aren't good at self selecting books to read.
On the topic of gonzo journalism I wonder if I could drop a lot of acid and smoke pounds of weed and write something like "the gonzo guide to freebsd" with lines like "VLM knew he was in trouble when the install flash drive he was holding seemed to change shape into a frog and hopped away". People like books like that about the Vietnam War or Hells Angels or Hippies so why not installing FreeBSD?
Something to think about is once workplaces settle down the documentation always improves. Very few 1st year carpenter's apprentices are handed a structural engineering statics book either accidentally or on purpose. Someday, when its settled what a noob is and what a noob does, they'll be some pretty good noob books out there.
(Score: 1, Interesting) by Anonymous Coward on Monday June 05 2017, @03:16PM (1 child)
Before it was called "Gonzo" there was Normal Mailer's "The Naked and the Dead" -- this sets a very high bar for the "hyper-realistic war documentary fiction" category, which I believe Mailer invented(?), although in other writings Mailer says that he was inspired by Faulkner...
Tom Wolfe and Hunter Thompson surely read Mailer when they were starting out.
---
> flash drive he was holding seemed to change shape into a frog and hopped away
This reminded me of a trippy college evening. I got back to the co-op where I was living and discovered that it was my day for kp. Had to wash the dishes for 30 people, while the dishes were grinning at me and and trying to jump out of my hand and onto the floor. I focused hard and none of them escaped!
(Score: 2) by VLM on Monday June 05 2017, @03:41PM
Interesting I donno how I missed that book...
I'm very familiar with Leckie "Helmet for my pillow" and Sledge "With the old breed" and its interesting they didn't write their books until decades after the war.
A lot of gonzo seems to be of the "alienated journalist is LARPing as not really a journalist not really a participant and high on drugs most of the time", I wouldn't say "Dispatches" is very realistic portrayal of life as either a REMF or a front line grunt, its a realistic portrayal of kind of a journalist/tourist. Toward the end of "Dispatches" the author gets super alienated because he's not even a real journalist because he's writing for a monthly magazine and "real" journalists either write for daily newspapers or are weekly photojournalists so he spent an inordinate amount of time baking and goofing off. I kind of like the book "Dispatches" but I get the feeling the author himself is (or at least was as a kid) a degenerate piece of shit, none the less with some writing skill.
Now, Sledge and Leckie were front line grunts, and tell quite a story. Also they're likable unlike the poseurs Thompson and the "Dispatches" author.