SoylentNews

Free Software is Suffering Because Coders Don’t Know How to Write Documentation

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

Arthur T Knackerbracket has found the following story:

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

• Re:What is it for? Re:What is it for? (Score: 2) by choose another one on Monday June 05 2017, @06:27PM (1 child)

  by choose another one (515) 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.

  Parent

  Starting Score:	1		point
  Karma-Bonus Modifier		+1
  Total Score:		2

• Re:What is it for? (Score: 2) by VLM on Monday June 05 2017, @07:49PM

  by VLM (445) 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.

  Parent