[Info-vax] OT(?): documentation: who needs it? You and me, but not them

[johnwallace4 at yahoo.co.uk]

On Saturday, 26 October 2013 02:19:12 UTC+1, Simon Clubley  wrote:
> On 2013-10-25, Rich Jordan <jordan at ccs4vms.com> wrote:
> 
> > On Thursday, October 24, 2013 6:18:59 PM UTC-5, Stephen Hoffman wrote:
> 
> >> re: is the SMTP configuration change documented?
> 
> >> 
> 
> >> First person that finds their way to page 1-13 in 
> 
> >> 
> 
> >> <http://h71000.www7.hp.com/doc/84final/tcprn/tcpip_v57_rel_notes.pdf> 
> 
> >> 
> 
> >> wins the kewpie.
> 
> >> 
> 
> >
> 
> > Correct, there is available documentation.  However the actual product
> 
> > documentation has not.  If you go to the HP official documentation site, select
> 
> > TCPIP Services, and then the V5.7 tab, and the management guide and command
> 
> > references contain invalid information; I know they say they are V5.6 on the
> 
> > cover page, but they are listed for and accessible via V5.7... they should have
> 
> > been updated.
> 
> 
> 
> I strongly agree.
> 
> 
> 
> Who was responsible for releasing this functionality change in V5.7 ?
> 
> 
> 
> Was it still Nashua or was this work done in India ?
> 
> 
> 
> In either case, whoever didn't update the documentation to reflect the
> 
> change in functionality made a big mistake; it's the kind of thing which
> 
> simply would have been unheard of a few years ago and would have been
> 
> regarded as a release blocker.
> 
> 
> 
> BTW, documentation doesn't seem to be all that important these days
> 
> in various environments. :-(
> 
> 
> 
> Unrelated to VMS, I am currently pulling together documentation on a
> 
> embedded board with a Chinese Allwinner Cortex-A8 MCU. The level of
> 
> the Allwinner MCU specific documentation, especially when compared to
> 
> MCU specific documentation from traditional manufacturers such as TI
> 
> and NXP is absolutely pathetic.
> 
> 
> 
> It seems like in some environments/cultures, no one cares about decent
> 
> documentation any more; in the embedded world in those cultures all you
> 
> get a blob of reference code covering some of the functionality instead
> 
> of the decent documentation. Even when the code is understandable, all
> 
> you get from it is _how_ something works, but not _why_ it works that way.
> 
> 
> 
> Knowledge gained in that way is fragile; you don't get any conceptual
> 
> level overview for how the device works and how, for example, various
> 
> register settings are interconnected in general.
> 
> 
> 
> So in summary, yes, bad documentation is more than a bit of a sore point
> 
> for me at the moment. :-(
> 
> 
> 
> Simon.
> 
> 
> 
> -- 
> 
> Simon Clubley, clubley at remove_me.eisner.decus.org-Earth.UFP
> 
> Microsoft: Bringing you 1980s technology to a 21st century world

Agreed in principle, but...

Why would Allwinner care about documentation and/or source code (for the likes 
of you or me) for their specific variations on the ARM theme? 

Think about it.

Companies like Allwinner have quite interesting products which have a tiny 
handful of Tier 1 customers, who are buying chips by the million (typically to 
go in Android kit), and that handful of Tier 1 system builder companies get 
direct support for hw and sw from the chip designers. Maybe the chip designers 
even listen to what their customers want and are willing to pay for.

Putting sufficient useful documentation together, in the same way as the 
"commodity" chip designers of earlier eras would have done, in order to make 
these products of interest to people buying handsful of chips through Farnell 
or Digikey or whoever, is of little interest to these folks. Especially as by 
the time they've got the errors out of the documentation, the chip will have 
been replaced by a cheaper and faster alternative.

I'm vaguely interested in what you're up to with one of these that needs chip 
level docs (but maybe that discussion doesn't belong here).

Lots of things (but by no means all) can nowadays be done with system level 
docs for things like Raspberry Pi (where decent docs are explicitly a goal - 
sometimes comprised by Broadcom-specific "reference blobs"), or by BeagleBone 
and other conceptually similar stuff targeted at the relatively low volume 
market. We shouldn't expect to go to someone who designs for a highhvolume 
tablet manufacturer and get chip level docs from them. 

I have a feeling that the market isn't what it used to be. And not all the changes are what you and I would class as improvements.

Best of luck anyway - you may need it!