Am I old, or is it really unprofessional to publish an API and have the 
official documentation for the function call be "go read this guy's blog 
from last June to see an example of how to use this API"? Even if the guy is 
the one that implemented it?

I mean, that's the crap I'd expect with like an OSS Drupal plug-in, not a 
supported product by someone like Microsoft.

Programming has really gone from "what you know" to "who you talk to" this 
last decade or so.

-- 
Darren New, San Diego CA, USA (PST)
   "Coding without comments is like
    driving without turn signals."

Post a reply to this message

Darren New <dne### [at] sanrrcom> wrote:
> Programming has really gone from "what you know" to "who you talk to" this
> last decade or so.

indeed, programming today is a social network activity performed by drones
learning from stackoverflow.com...

Post a reply to this message

Darren New <dne### [at] sanrrcom> wrote:
> Programming has really gone from "what you know" to "who you talk to" this 
> last decade or so.

  Some companies are not that lazy. For example Apple has very extensive and
ample documentation on their development environments (in the form of
tutorials and reference manuals).

  Of course then there are those who either have no documentation to
speak of, or just some lazy barely documented doxygen-generated listing
of classes (which is often a couple of versions older than the most recent
distribution of the library). Yes, I have concrete experience of exactly
this.

-- 
                                                          - Warp

Post a reply to this message

On 4/13/2011 7:30 PM, Darren New wrote:
> Am I old, or is it really unprofessional to publish an API and have the
> official documentation for the function call be "go read this guy's blog
> from last June to see an example of how to use this API"? Even if the
> guy is the one that implemented it?
>
> I mean, that's the crap I'd expect with like an OSS Drupal plug-in, not
> a supported product by someone like Microsoft.
>
Oh, you mean like posting an API reference, which refers to a demo 
application, which isn't hosted on the site, and hasn't been available 
since 1992, or so, when the original book the article was copied out of 
was published (and it didn't occur to them to either a) use a different 
damn name for their demos, instead of the same one for *all* of them, or 
b) repost the source as part of the article? Nope, I expect literally 
nothing less from Microsoft than this sort of crap. lol

Post a reply to this message

On 4/13/2011 23:45, Warp wrote:
>    Some companies are not that lazy. For example Apple has very extensive and
> ample documentation on their development environments (in the form of
> tutorials and reference manuals).

MS didn't *used* to be that bad. The XNA stuff just seems particularly 
poorly documented, like it's not really strategic or something. The blog 
posting is great. Detailed, examples, etc. Why the heck not copy it into the 
documentation for the routine, instead of seeing "go see the blog post at 
the URL for details of how to use this call"? (Of course, the answer is 
probably that someone would have to translate it, get it approved by 
lawyers, etc.)

Most of the MS documentation is pretty good, really, but it has indeed been 
going downhill.

>    Of course then there are those who either have no documentation to
> speak of, or just some lazy barely documented doxygen-generated listing
> of classes (which is often a couple of versions older than the most recent
> distribution of the library). Yes, I have concrete experience of exactly
> this.

That's my complaint. Maybe it's just the XNA stuff, but most of it is 
doxygen not-very-commented stuff, with third-party forums and blogs filling 
in.  I think I just grew up in a time frame when learning about computers 
came from books, so surfing around the whole world trying to guess the right 
keywords to see who already solved your problem is annoying. I mean, I 
learned APL by sitting down and reading the manual for the APL interpreter. 
Are you really going to learn something like Ruby from scratch by reading 
nothing but the documentation that comes with the interpreter? Hell, even 
the "official" Ruby book has statements in it that say things like "It seems 
to work like this..."  (That's when I gave up on Ruby, incidentally - when I 
realized the guy writing the O'Reilly book was guessing how it actually worked.)

Especially when there's like 4 or 5 versions (and half a dozen CTP and RC 
versions) in the last 4 years, and all the old posts are still hanging 
around, most of which don't mention what version they're using.

-- 
Darren New, San Diego CA, USA (PST)
   "Coding without comments is like
    driving without turn signals."

Post a reply to this message

On 14/04/2011 17:25, Darren New wrote:

> MS didn't *used* to be that bad. The XNA stuff just seems particularly
> poorly documented, like it's not really strategic or something.

> Most of the MS documentation is pretty good, really, but it has indeed
> been going downhill.

The thing that annoys me about MS products is that if one day somebody 
phones you up and says "when I try to open Outlook it says error 28123", 
there is *no way* of discovering WTF this code actually means. If you 
open the settings for a program and some option has an ambiguous name, 
you can't look up what the setting actually does. [Bonus points for 
inventing the "help button" which informs you "no help is available for 
this item".] If I see something in Task Manager called mdm.exe, there is 
no way of finding out what this is, what it actually does, or anything 
about it. "Cryptographic Services". Cryptography *for what*? So, do I 
need this? Is it safe to turn it off? Or is it vital?

In short, almost nothing is documented. I find this extremely frustrating.

> I think I just grew up in a time frame when learning about
> computers came from books, so surfing around the whole world trying to
> guess the right keywords to see who already solved your problem is
> annoying. I mean, I learned APL by sitting down and reading the manual
> for the APL interpreter. Are you really going to learn something like
> Ruby from scratch by reading nothing but the documentation that comes
> with the interpreter? Hell, even the "official" Ruby book has statements
> in it that say things like "It seems to work like this..." (That's when
> I gave up on Ruby, incidentally - when I realized the guy writing the
> O'Reilly book was guessing how it actually worked.)
>
> Especially when there's like 4 or 5 versions (and half a dozen CTP and
> RC versions) in the last 4 years, and all the old posts are still
> hanging around, most of which don't mention what version they're using.

The Commodore 64 came with an extensive (yet surprisingly small) user 
manual which, as well as telling you how to wire up the device [which 
admittedly isn't that hard] and advertising all the addons you could buy 
[not many], also tells you everything there is to know about programming 
in BASIC. Well, except for the part about how to *design* a program. It 
tells you exactly what every single command and function in the language 
does. [Admittedly, there aren't that many to describe.]

The Sam Coupe had an excellent manual. Actually, it was excellent 
hardware. It's surprising that nobody's ever heard of it. If you imagine 
a C64 or a ZX Spectrum with a 6MHz CPU, 256KB RAM (upgradable to 4MB), 
128-colour graphics, stereo digital sound and an implementation of BASIC 
with primitives like drawing a curved line with one command, that's 
basically the Sam. The manual was extensive, assumed no prior experience 
with computers, and told you EVERYTHING.

Then again, back in the 1980s, how many home users had experience of 
computers?

Today, if you buy a new PC, you don't get a manual at all. Then again, 
it doesn't [usually] come with any software. Or if it does, it's just a 
copy of Windows. Windows sometimes has a small pamphlet to tell you how 
to work a mouse, and that's about it.

If you want to learn to program in Haskell... good luck. There's the 
official language specification - which is intended for compiler 
writers, and hence assumes that you already know the difference between 
the untyped lambda calculus and the simply-typed lambda calculus, and 
why the fixed-point operator cannot exist in the latter. (Interestingly, 
the language spec is linked from the Haskell homepage. WTF?) If that 
doesn't do it for you, there's maybe three books you could buy, or it's 
blogs and wiki pages.

The Haskell compiler, GHC, has a number of Haskell extensions that you 
can switch on. The documentation for these is... minimal. Most of them 
say "for more information see this [blog | wiki page | mailing list 
email | PDF research paper]".

Of course, GHC is a product given away for free. Presumably we should be 
grateful that the developers wrote any documentation at all. They are 
rather busy trying to sort out the 468 open tickets on the bug tracker. 
(I didn't pluck that number out of the air. As of 11:55 BST on 
15-Apr-2011, there are 468 open tickets.)

When you *buy* an expensive commercial product, you expect better than 
this. Sometimes you get it, sometimes you don't.

Post a reply to this message

On 15/04/2011 11:55 AM, Invisible wrote:
> Then again, back in the 1980s, how many home users had experience of
> computers?
>

All of them or they wouldn't be users :-P

Most people I knew who bought a home computer then had experience of 
them from work.
A question I was often asked was "Why do you want an computer and what 
can you do with it?"

> Today, if you buy a new PC, you don't get a manual at all.

Every laptop I have bought has come with either a CD/DVD manual or a 
manual installed on the HDD.

> Then again,
> it doesn't [usually] come with any software. Or if it does, it's just a
> copy of Windows. Windows sometimes has a small pamphlet to tell you how
> to work a mouse, and that's about it.

You don't get a manual with a toaster or an electric kettle and that's 
what home computers are now a days, white goods.
Outside of this group* I don't know anyone who uses a computer at home 
for anything other than email, Skype, browsing the internet or 
downloading books, films, music, or porn.


* And we are special (I know because I went to a special school) ;-)

-- 
Regards
     Stephen

Post a reply to this message

On 15/04/2011 13:34, Stephen wrote:
> On 15/04/2011 11:55 AM, Invisible wrote:
>> Then again, back in the 1980s, how many home users had experience of
>> computers?
>
> All of them or they wouldn't be users :-P
>
> Most people I knew who bought a home computer then had experience of
> them from work.

Really? Interesting... I'm not old enough to know, but I didn't think 
that was actually the case in the 80s.

> A question I was often asked was "Why do you want an computer and what
> can you do with it?"

Now *that* is a question worth asking!

The possible answers include:
- Play video games.
- Type letters without having to retype the entire thing if you make one 
tiny mistake.
- Store large amounts of information without filling your filling 
cabinet. [Assuming you write the software to load and store this stuff 
and don't mind waiting 2 hours for it to load off cassette tape.]

>> Today, if you buy a new PC, you don't get a manual at all.
>
> Every laptop I have bought has come with either a CD/DVD manual or a
> manual installed on the HDD.

Really?

> You don't get a manual with a toaster or an electric kettle and that's
> what home computers are now a days, white goods.

Actually, usually you *do* get a manual with toasters and kettles, even 
though you don't need one! o_O

> Outside of this group* I don't know anyone who uses a computer at home
> for anything other than email, Skype, browsing the internet or
> downloading books, films, music, or porn.

What, you don't know any gamers? ;-)

> * And we are special (I know because I went to a special school) ;-)

Vehraaay thpesshul. :-P

Post a reply to this message

On 15/04/2011 1:51 PM, Invisible wrote:
> On 15/04/2011 13:34, Stephen wrote:
>> On 15/04/2011 11:55 AM, Invisible wrote:
>>> Then again, back in the 1980s, how many home users had experience of
>>> computers?
>>
>> All of them or they wouldn't be users :-P
>>
>> Most people I knew who bought a home computer then had experience of
>> them from work.
>
> Really? Interesting... I'm not old enough to know, but I didn't think
> that was actually the case in the 80s.

 From my memory. The very first time I heard anyone outside of work 
talking "computer speak" was in 1996 when I overheard two women talking 
about a C:\ drive, in the street. Slatterns! ;-)

>
>> A question I was often asked was "Why do you want an computer and what
>> can you do with it?"
>
> Now *that* is a question worth asking!
>
> The possible answers include:
> - Play video games.

There weren't any then. Text games or wireline graphics.

> - Type letters without having to retype the entire thing if you make one
> tiny mistake.

Most people used pen and paper. Most people could not type and the ones 
that could probable learned how to at commercial lessons or typing classes.

> - Store large amounts of information without filling your filling
> cabinet. [Assuming you write the software to load and store this stuff
> and don't mind waiting 2 hours for it to load off cassette tape.]
>
I don't think that there was any need back then. Paper ruled!


You probably don't realise how much things have changed just in my 
lifetime.
Cars were for the rich, children could play in the street without fear 
of getting knocked down. But collecting number plates (I don't mean 
ripping them off cars) had just gone out of fashion but adults thought 
that it was a suitable hobby. Ballpoint pens were banned in schools, we 
used dip pens. (That changed when I went to high school). The first 
check book I got cost 1/2d per check for stamp duty. People used to go 
out to the airport to see planes taking off and landing for 
entertainment. Foreign holidays were unheard of for most people.
Now if Larry Hudson is about I'd like to hear how things have changed in 
his lifetime.

>>> Today, if you buy a new PC, you don't get a manual at all.
>>
>> Every laptop I have bought has come with either a CD/DVD manual or a
>> manual installed on the HDD.
>
> Really?

Yes, the ones I've bought. This one is number six. My first was bought 
around 1997.

>
>> You don't get a manual with a toaster or an electric kettle and that's
>> what home computers are now a days, white goods.
>
> Actually, usually you *do* get a manual with toasters and kettles, even
> though you don't need one! o_O
>

Yes, plug it in and clean with a damp cloth but not at the same time.

>> Outside of this group* I don't know anyone who uses a computer at home
>> for anything other than email, Skype, browsing the internet or
>> downloading books, films, music, or porn.
>
> What, you don't know any gamers? ;-)
>

Only you. My brother-in-law plays some sort of fantasy football game but 
that is a solo thing, I think. I don't play games myself I'm not any 
good at them.

>> * And we are special (I know because I went to a special school) ;-)
>
> Vehraaay thpesshul. :-P

You got the reference (I thought that the language may have changed).

-- 
Regards
     Stephen

Post a reply to this message

>>> Most people I knew who bought a home computer then had experience of
>>> them from work.
>>
>> Really? Interesting... I'm not old enough to know, but I didn't think
>> that was actually the case in the 80s.
>
> From my memory.

That's not how I remember it, but hey, OK...

>> The possible answers include:
>> - Play video games.
>
> There weren't any then. Text games or wireline graphics.

I certainly remember knowing several people who owned a C64 or a ZX 
Spectrum or something similar exclusively so they could play games on it.

>> - Type letters without having to retype the entire thing if you make one
>> tiny mistake.
>
> Most people used pen and paper. Most people could not type and the ones
> that could probable learned how to at commercial lessons or typing classes.

Again, I certainly remember us owning a typewriter. Me and my sister 
used to type stuff on it just for entertainment. Having a word processor 
made life so much easier. And then my parents got a dot matrix printer 
to go with it...

As late as 1995, one of the people at school paid hundreds of pounds for 
an "electronic type writer" that was basically a computer keyboard, dot 
matrix printer and a tiny LCD all in one unit. So, like a real 
typewriter, but computerised. (I don't think you could even turn it off 
without losing your work, mind you...)

>> - Store large amounts of information without filling your filling
>> cabinet. [Assuming you write the software to load and store this stuff
>> and don't mind waiting 2 hours for it to load off cassette tape.]
>>
> I don't think that there was any need back then. Paper ruled!

Yeah, I'm having trouble thinking of any large volume of information 
that you'd actually bother keeping that would be too large to hold on 
paper... The contents of your filofax maybe.

> You probably don't realise how much things have changed just in my
> lifetime.

I know how much they changed in *my* lifetime, but I'm not quite as old. ;-)

> Cars were for the rich, children could play in the street without fear
> of getting knocked down. But collecting number plates (I don't mean
> ripping them off cars) had just gone out of fashion but adults thought
> that it was a suitable hobby. Ballpoint pens were banned in schools, we
> used dip pens. (That changed when I went to high school). The first
> check book I got cost 1/2d per check for stamp duty. People used to go
> out to the airport to see planes taking off and landing for
> entertainment. Foreign holidays were unheard of for most people.

As I say, I'm younger.

When I was a kid, almost everyone had a TV, most people had a knackered 
old car that they spent months per year fixing, and some but not all 
families owned an 8-bit home computer of some sort. I can distinctly 
remember being utterly addicted to Space Invaders, so much so that I 
didn't want to leave my friend's room when mum said it was time to go home.

My parents bought a ZX Spectrum so they could run "educational" type 
games on it for me and my sister. Later my dad had a Commodore Plus4. 
That died spectacularly; left on his bed, the air vents apparently got 
blocked, and I came back to find that the tape hadn't finished loading. 
Instead, the screen was now pink with diagonal white stripes and random 
flashing glyphs. It never worked again, so we got a C64. Pitty; the 
Plus4 was better.

>>> Every laptop I have bought has come with either a CD/DVD manual or a
>>> manual installed on the HDD.
>>
>> Really?
>
> Yes, the ones I've bought. This one is number six. My first was bought
> around 1997.

I haven't seen that one yet. Then again, I've only really got experience 
of one brand - Acer.

Unless you count that IBM thing I was allowed to use, way back in 
1990-something. You know, when only business executives, accountants and 
professional programmers could such things. Cyan and magenta screen that 
rippled when you touched it. VGA graphics FTW! :-D

> Yes, plug it in and clean with a damp cloth but not at the same time.

During boiling, the outside of the kettle may become hot. This does not 
indicate a fault condition.

>> What, you don't know any gamers? ;-)
>
> Only you. My brother-in-law plays some sort of fantasy football game but
> that is a solo thing, I think. I don't play games myself I'm not any
> good at them.

Solo games are still games. ;-)

>>> * And we are special (I know because I went to a special school) ;-)
>>
>> Vehraaay thpesshul. :-P
>
> You got the reference (I thought that the language may have changed).

Oh, I'm sure it has. But what would I know about that? ;-)

Post a reply to this message