Stories
Slash Boxes
Comments

SoylentNews is people

posted by n1 on Monday June 05 2017, @10:15AM   Printer-friendly
from the git-gud dept.

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.

2017 Open Source Survey

-- submitted from IRC


Original Submission

 
This discussion has been archived. No new comments can be posted.
Display Options Threshold/Breakthrough Mark All as Read Mark All as Unread
The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
  • (Score: 3, Interesting) by VLM on Monday June 05 2017, @05:03PM (4 children)

    by VLM (445) Subscriber Badge on Monday June 05 2017, @05:03PM (#520838)

    better docs

    That brings us back to what does better mean. For a laugh try my "vRealize challenge" and try to decode the marketing-speak in less than five minutes.

    I'd say in excess of 95% of the vmware website is useless. Its even funnier in that the target is moving fast that esx 6.5 can't really be used with 5.0 docs. A practical example is the legacy FLASH web ui for vcenter is the only option for entering license keys with 6.5, you can't enter license keys using the HTML 5.0 web interface and the instructions are INFURIATING as anything older than six months on the vmware website or "helpful" blogger posts on the internet don't acknowledge the fact. But if you're running 6.5 and can in freaking 2017 find a way to run a web browser with legacy old fashioned FLASH, and then use the legacy FLASH web interface, then and only then can you enter licensing key information into vCenter. Otherwise the html 5 UI is visually identical other than that option is missing. Hilarious, huh? The entire system is like that, top to bottom across the whole field. Nothing but the equivalent of "in-jokes" as far as the eye can see.

    I've had some hilarious adventures converting standard switches to distributed switches, very herculean efforts if you're playing "stupid VLAN games". From memory you can only configure or use distributed switches from vCenter/vSphere flash web page UI but you can only add and remove standard switches from the individual ESXi host web interface. So yeah there's three web interfaces for "the same thing" there's the ESX host UI, the flash legacy UI for vsphere, and the vcenter html5.0. And some tasks can only be done in 1 or 2 of the three UI. Hilarious. And the way its documented is you figure it out the hard way. Which is why VCP cert people, etc, earn such big bucks.

    In fact if you're playing stupid VLAN games you can't install the second half of vCenter without some interference to the ESX host its being installed upon, it'll insist on dropping on the probably standard switch on vlan 0 regardless what vlan your mgmt network actually uses. And then there's tribal knowledge thats only semi-documented (well, maybe its in release notes now) like configuring more than one DNS server crashes the vCenter installation (WTF?)

    Also sometimes vSAN needs dead chicken waved over it. vSAN why are you marking a disk as unhealthy for no discernible reason, why why why ...

    vSAN is also hilarious in that AFAIK the only way to create a new vSAN is to do it as part of installing a new vCenter appliance. I know the html5.0 web UI can't create a cluster using vSAN (I think?) maybe there's some way from an already installed vcenter using the legacy FLASH web UI?

    The joy of scratch partitions and log folders is legendarily hilarious. Just don't even go there.

    You can guess what I've been playing with for the last two weeks in my spare time. VMware is aggravating and ungodly expensive, but fun when it works.

    there is no money to pay someone to write docs, the programmer doesn't do it for free since there is no "itch to scratch"

    I have seen this in decline with the rise of unit testing and halfway attempts at unit testing. Then its a pretty short step from "cut and paste this test from unit testing into the docs file and call it a verified and tested example and we're done here" I've seen worse.

    I've also seen programmers "hate writing docs" but they really hate writing corporate-ized docs. Real docs not so bad, most of the time.

    I've been programming stuff since '81 and as I've become a better programmer I've gotten better about writing docs. It might be a condemnation of the entire field that when everyone's a noob, everyone writes docs like a noob, but as the field matures the professionals separate out and docs just aren't that bad. If you can't express yourself in Her Majesties English then you sure as hell can't express yourself in Clojure or SQL.

    Starting Score:    1  point
    Moderation   +1  
       Interesting=1, Total=1
    Extra 'Interesting' Modifier   0  
    Karma-Bonus Modifier   +1  

    Total Score:   3  
  • (Score: 2) by choose another one on Monday June 05 2017, @06:27PM (1 child)

    by choose another one (515) Subscriber Badge on Monday June 05 2017, @06:27PM (#520887)

    That brings us back to what does better mean.

    Yeah, maybe if I had said something like "more useful" that would have been better... :-)

    For a laugh try my "vRealize challenge" and try to decode the marketing-speak in less than five minutes.

    Decoded - the answer reduces to "it's marketing BS".

    Actually it looks like it's a sort of management console for creating, managing and monitoring "everything" from bare metal (obviously it can't create bare metal, but probably just gives an undocumented error number if you try) through virtual stuff to cloudy shite (and hybrids of). It therefore gives you one unholy mess of a tool to do everything badly, it won't give you all the options you'd have by doing things directly using individual tools, yet it is almost certainly a cobbled together collection of individual tools itself - and they probably don't look alike, function alike or indeed have any useful commonality. On top of that it throws templates and things so you can do more stuff badly and with even less flexibility - VMWares idea of what you want rather than what you actually wanted. Then the UI(s) are probably so bad that it needs APIs/Orchestration (i.e. scripting) to do do anything complex - by the time you've learnt that you might as well have just scripted the underlying stuff directly.

    How did I do? Took longer to write that description than to read marketing :-)

    I have seen this in decline with the rise of unit testing

    Me too, in fact it is more or less backed into TDD definition - the test is the spec for what the unit does and is therefore the documentation. At least the docs can't get out of date I suppose.

    • (Score: 2) by VLM on Monday June 05 2017, @07:49PM

      by VLM (445) Subscriber Badge on Monday June 05 2017, @07:49PM (#520936)

      Actually it looks like it's a sort of management console for creating, managing and monitoring "everything" from bare metal (obviously it can't create bare metal, but probably just gives an undocumented error number if you try) through virtual stuff to cloudy shite (and hybrids of). It therefore gives you one unholy mess of a tool to do everything badly, it won't give you all the options you'd have by doing things directly using individual tools, yet it is almost certainly a cobbled together collection of individual tools itself - and they probably don't look alike, function alike or indeed have any useful commonality. On top of that it throws templates and things so you can do more stuff badly and with even less flexibility - VMWares idea of what you want rather than what you actually wanted.

      Ah that's just vSphere. Other than having multiple almost identical appearance web UI, vSphere isn't all that bad. The cobbling is more related to licensing. You can buy a system without disaster recovery automation so there are aspects to openstack that are baked into the cake for restoral of a dead host that have to be kinda grafted onto vSphere and can't be the default. From memory you turn on DRS migration at the cluster level whereas on openstack there are no pay options so its kinda enabled by default AFAIK.

      Another weird example is openstack has "neutron" the network mismanager with everything baked in and you can't really do vmware "standard ethernet switches" with openstack, AFAIK, because openstack only offers distributed switching but you can buy ESX hosts without vSphere to manage distributed ethernet switches so being licenseable it has to be bolted on. If you're doing virtualbox or just screwing around on linux, vmware "standard ethernet switches" are just linux bridge networking, and what you configure has no effect on the config of other hosts. Distributed switches are more than just automation there's some weird shared uplink routing stuff going on that I haven't explored.

      Or in summary, ironically because vmware isn't free, there are options to purchase for networking that make networking more complicated for vmware than for openstack, where everythings free, so why would anyone ever use anything but distributed ethernet switches on simpler openstack?

      Then the UI(s) are probably so bad that it needs APIs/Orchestration (i.e. scripting) to do do anything complex - by the time you've learnt that you might as well have just scripted the underlying stuff directly.

      Yeah that's it pretty much. I'm a bit fuzzy on it myself. There is an API to mess with vmware stuff. Maybe that API is part of vRealize LOL.

  • (Score: 2) by kaszz on Monday June 05 2017, @11:50PM (1 child)

    by kaszz (4211) on Monday June 05 2017, @11:50PM (#521053) Journal

    Without proper docs it's possible to charge more for support calls..

    • (Score: 2) by VLM on Tuesday June 06 2017, @03:48PM

      by VLM (445) Subscriber Badge on Tuesday June 06 2017, @03:48PM (#521377)

      In theory true but even if generally true there's a spectrum of it and Cisco for example used to have legendary good docs online AND I was personally involved at a company where Cisco Certs meant a price deduction on the huge bill, a deduction big enough that paying me to shitpost and play video games all day would still have been a net profit to the company. Of course rather than shitpost and video I got stuck providing BGP support to our customers, which I was very good at although it got boring after the 50th time some guy tried to send us a 0/0 route or wanted to advertise his previous ISP's subnet, LOL. "Well see I was tryin to redistribute my RIP routes into BGP" "Excuse me sir WTF are you doing, STFU and configure it the way I tell you to" (although I spent about four hours per customer or so it seemed doing it very politely, although the previous one liner summarized it remarkably well). I also felt like a hostage rescue negotiator some days "I see my routes are dampened because of flapping, what does that mean, I guess I'll go reboot my router a couple times till it starts working again" "nooooooooo nooooo don't jump your router has a lot to live for nooooooo"