[noen]

About 7 years ago I was in a meeting with a former Windows core graphics engineer.

My team was attempting to figure out some extremely obtuse workflows with MediaFountain and DirectX.

We had a meeting with this guy and a couple of the other engineers that wrote the APIs and the implementation underneath.

This particular guy literally chuckled as we aired our frustrations and this was his response:

“Yeah you won’t figure those APIs out from the documentation. It was on purpose. You have to go buy the book.”

Proceeded to explain to me that this was how he, and many other core Windows engineers lined their pockets for years - write complex implementations, do the absolute bare minimum documentation, then take a 6 month sabbatical and publish a reference book that was absolutely required to actually use the API.

Apparently many of these guys made 10-20x their salaries on this grift and it didn’t really stop until the mid 2000’s.

[krylon]

> “Yeah you won’t figure those APIs out from the documentation. It was on purpose. You have to go buy the book.”

I KNEW it!!! In a prior job, I had the unpleasant task of shepherding a SharePoint installation, and was incredibly frustrated at the documentation AND the available literature. I jokingly commented it must be to keep all those SharePoint consultants busy.

Now I think that might actually have been the case. Those poor souls...

[whstl]

Yep. I also suffered with SharePoint in the late aughts, and eventually consultants were brought in to add some stupid custom feature to out Intranet Wiki that required a month of custom coding.

Plenty of other companies doing that as well. Pretty much every ERP company, for example: from big ones like SAP or IBM, to the ones only popular in their home state.

I remember a consultant telling me “you don’t get it, the point of our app is that you can build ANYTHING the customer withs it”. Well, so is the point of, say, Python.

[BizarroLand]

I feel like this is much of why I hate windows server administration compared to linux.

If you want to know something on linux, either read the man pages or check online. Someone probably wrote a blog post 13 years ago (but carefully updated over the years to keep the information fresh and accurate) that details exactly what you need to do step by step, along with a conversation about the options that you have as you are instantiating the server and asks for nothing in return other than the pleasure of having shared their knowledge.

If you want to know something on Windows, you can either get extremely lucky and figure it out yourself after hours of trial and error or find the one post on the internet that details the specific issue you have.

Learning how to administrate windows servers from official Microsoft sites? That is like reading an encyclopedia to learn how to do surgery. Microsoft's official education webpages on windows administration is the end user equivalent of watching a youtube video on how to rebuild a lawnmower engine when you need to put gas in your weed eater. It's in the ballpark range of the information you need but is so fundamentally inept and terribly wrong for a useful purpose that it boggles the mind how there isn't a better source of information.

And now we learn that there is a better source of information. Printed books. Intentionally sold by the people who wrote the terrible online documentation.

Because this is 1954 and we don't have any other options, right?

[SilasX]

Haha yeah that's why I cringe whenever someone reassures me that Open Source software models are profitable, as "you can just make money from selling the consulting services for it!" Okay, but what are you incentivizing there, then?

[arethuza]

That reminds me of the lines from movie of the Big Short:

"They're not confessing", "They're bragging".

[geoffdunbar]

I worked at Microsoft from 1996 to 2011. I was a SDE and lead on Windows Media and Media Foundation. This is a cute story, but I never heard of anything like this. There is no way my management would have approved any time off to write a book on a Microsoft product. Sabbatical is possible, but everyone I knew that qualified for a sabbatical was already filthy rich from early 90s stock options, and used that time to sail around the world or something like that.

I can't rule out that such a thing did happen at Microsoft in groups that I wasn't part of, but I would be stunned if it was more than a couple of people.

[Karellen]

Well, I hope you inquired as to whether he was born that much of an asshole, or if he had to work his whole life to achieve it, and then refused to address him as anything other than "fucking wanker" for the remainder of the meeting. On behalf of the rest of us.

[mschaef]

> he, and many other core Windows engineers lined their pockets for years - write complex implementations, do the absolute bare minimum documentation, then take a 6 month sabbatical and publish a reference book that was absolutely required to actually use the API.

If you don't spend enough time on design, it's easy to wind up with an overcomplicated API that lacks documentation.

I wonder if the book was just a "convenient side benefit" of Microsoft's general failure to invest in developer UX. (At least at the time.)

[ufmace]

I wouldn't be surprised if the actual progression went like:

Senior engineers end up with a moderately complex API for various bureaucratic reasons and don't have time to document it well -> Some junior engineer trying to be helpful writes up instructions as he figures out how to use it -> Junior engineer, still trying to be helpful, can't find anywhere good to put these instructions he wrote, so he gets a book published of it -> Rakes in extra money from said book -> Senior engineers see this and think, whoa, that's a nice scheme, but why should this newbie get all the $$$, let's do it more on purpose! -> Next thing you know, all the APIs are actually more complex and everyone's got a book

[8chanAnon]

>If you don't spend enough time on design, it's easy to wind up with an overcomplicated API that lacks documentation.

That sounds about right. Creeping featurism gets ahead of the team's ability to document it all before the product has to be delivered. Hence the need to take some time off and write a book about it. It's not necessarily an evil plan but just the way it works sometimes. Writing documentation is hard. Delivering the documentation on time is even harder.

[marricks]

I wonder that about many of the corporate web frameworks out there too. The guides and evangelist say it's so easy but they have the most dog shit docs out there but hey, plenty of training you can pay for to get certified.

It made me think I was an idiot until I talked to a couple other folks (who didn't have a financial reason to say it was easy) and they agreed it was horrible documentation.

One reason I love open source: you won't have folks clamoring to use or improve your system if it's too shitty. To reach great levels of incomprehensibility you really need corporate backing.

[fouc]

That's a rather profitable twist on the classic "job security" strategy.

[matheusmoreira]

> It was on purpose. You have to go buy the book.

I don't think I'll ever find a better justification for copyright infringement in my lifetime.

[Jupe]

I recall, back when Windows 95 was released, a joke going around that went something like this: "Yes, Windows 95 is awesome and popular. So awesome and popular there are ~450 books written about how to use it!"

[robertlagrant]

This is the 2000s equivalent of get paid to work on a cool OSS project and then leave and immediately fork and start commercialisation.

[blueboo]

have a hard time believing that selling (tens of?) thousands of programming reference books brought in 10-20x salaries

or that entire teams would be following a pied piper leading to such a hellaciously complicated design, contrived to induce desperate reference buying??

It’s a funny thought but this is a fantasy

[rjh29]

Book part likely true. 6 month sabbatical and 10-20x salary probably not, or maybe just for like one lucky person.

[forinti]

I'm pretty sure Oracle works this way, but as company policy so that they can sell more support, consultancy, training, certification, etc.

[brettermeier]

SAP surely too...

[golergka]

Why wouldn't Microsoft sue them for this?

[dspillett]

A couple of immediate thoughts:

1. In many cases the books were published by Microsoft Press, so the company benefitted financially as well.

2. The engineers may have a defences in not being given time to document better initially due to project deadlines beyond their control, and in the work being signed-off at the time.

3. Some of both the above mixed with other reasons.

[mananaysiempre]

Microsoft (Press) published a fair number of these books—or at least books that were so much better than the reference docs that the latter could barely be said to explain anything, whatever the intent of the authors. This includes the classics: Petzold, Inside OLE, Essential COM, ...

[jollyllama]

They still had their monopoly, who cares? Besides, forcing people to invest time and to a lesser degree money to learn and get locked into your ecosystem is probably a net gain.

[usefulcat]

Good luck proving that case in court, especially if you have to prove intent.

[robertlagrant]

Can they? On what grounds?

[lloydatkinson]

Pretty shocking their managers let them get away with this. At least that’s stopped now.

[garganzol]

This is not a bad model in my opinion. Actually, it may be even better than the average. At least, you could buy the expertise compared to a total lack of it.

[incrudible]

Making an API knowingly and intentionally far more complicated than necessary is not just bad, it is evil. Doing it to enrich yourself personally is akin to embezzlement.

[SergeAx]

This is why sharing books is universally good.

[whalesalad]

It all makes sense.