[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.

[tivert]

> 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.

Yeah. The idea of generalized, reusable platforms are kind of a siren song for business types.

1. Executive notices the company has 5 apps that sit in a similar place in architectural diagrams. In a meeting, she says: "we have 5 different apps that are creating outputs based on various inputs according to business requirements. She declares, we should have ONE platform to replace those 5 apps. Savings!"

2. Platform team gets stood up. Starts to build the that app according to the new executive strategy.

3. Result: you get a shitty programming language (implemented as "configuration files") with a shitty transformation language. Turns out your platform was actually Java and XSLT, and your previous 5 apps could be understood as "configurations" of that platform.

4. New leadership takes over. The new "platform" gets de-platformized, because it sucks. Now the new platform will be built on the cloud!

[jjkaczor]

Ugh... see - they didn't "get it".

The point of SharePoint was to allow end-users to cobble things together themselves. One of the original design philosophies was "Excel on the web", hence the reliance on it's Lists as a core data structure (as inappropriate as it would of course become, when users started treating them like giant RDMS stores). My anecdata is from talking to some of the original design team members, from when Microsoft acquired it from VTI.

It was originally not intended for developers, it was for power-users. The fact that it was built on .NET technologies made it extensible though, and boom - quickly enough there was a huge market.

[whstl]

Well, here's the thing... you're not wrong. You're actually 100%... scratch that, 120% correct!

Software shouldn't really be a constant struggle. It shouldn't be about constantly forcing square objects into tiny round roles.

However, when you're an experienced developer that's easy to see. Sometimes even when you're inexperienced it's also easy... But when you're upper management, and a developer says "we shouldn't do that in Sharepoint" while Microsoft is telling them "this is 100% possible in Sharepoint" and the Microsoft approved consultancy says "this is extremely easy in Sharepoint", the developer ends up looking bad! :(

[arethuza]

One approach to dealing with that is to then suggest that if things are so easy then surely the consultancy would be willing to do the project on a fixed price basis?

[whstl]

Yeah, that would do the trick. But then again, in companies with thousands of employees this kinda things tends to get lost in translation between the multiple management layers, or when some over eager product manager decides to make their life goal adding some weird customization to SharePoint at any cost possible :/

[krylon]

It does allow people to build useful things, I'll give them that. But our company didn't have any power users, so us admins got handed the task of doing that as well. (manic laughter)

[jjkaczor]

Heh... I had a client, as recently as 2020 who barely had "users" - who didn't know how to perform basic computer operations (Cut/Copy/Paste, navigate menus, etc).

Hell - yesterday, I was working with a DBA over remote screen-sharing who had no idea how to enable the display of line-numbers in his preferred SQL text editor... (Or even that you have to press "OK" to save your changes in a modal dialog box...)

[krylon]

I don't mind if you build a lot of stuff on top of it. But if the vendor more or less withholds useful documentation from their customers on purpose to make them buy their training and certifications or hire their consultants, that's a dark pattern, isn't it?

[whstl]

Well, yes, definitely.

And that’s the business model of a lot of ERPs, especially mid-sized ones. Some of them even have private configuration software, and I even remember one having a private “special compiler” that was just applying something equivalent to a ROT13 to the code and zipping to discourage customization by customers.

But the crazy part is that you don’t even need to resort to this. Unless you’re SAP or something like that, there’s no chance in hell that a developer will want to hitch their career to your shitty ERP, so consulting it is.

[arethuza]

Any "platform" based approach is going to have that weakness - if you are in the domain where an ERP is a good fit then you'd be crazy not to use one, if you're problem isn't actually a good fit then you can end up in a whole world of pain and you'd be better off with a general purpose dev environment.

Unfortunately deciding this in advance can be tricky.

[whstl]

Yep, good points.

Indeed, during decision-making time, the people signing the checks always think that everything will fit nicely.

With customizable ERPs, what I have witnessed all my career were companies refusing to change their (universally hated, bureaucratic, insecure and inefficient) internal processes and having to pay more for customization.

The problem in the end is that there is rarely any shift, unless you have major cultural shift and oversight, coming from someone with the intention to save money and custom development time.

Inertia always wins.

[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?

[throw16180339]

This is pretty much why GCC supports dozens of architectures but has 5kloc functions.

[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...

[matheusmoreira]

No one has ever managed to successfully describe to me what SAP even does.

[majewsky]

That's like asking what Microsoft does. SAP has lots of different products, many from acquisitions, but the core product (what people think of when they say "SAP", although it's actually called S/4 HANA) is an ERP system. The Wikipedia article looks like a decent overview from what I can tell: https://en.wikipedia.org/wiki/Enterprise_resource_planning

Disclosure: I work at SAP, but on internal IT and not on any of the customer-visible products. (I don't know much about how S/4 HANA really works, except that I use it to view my payslip, enter my vacation days and such.)

[dizhn]

It's a bigger Excel.

[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.

[rob74]

4. they probably also didn't have the time for better API design, or the API design was done "by committee", and if you add to that the holy cow of "backwards compatibility", it's easy to see how an API might end up overcomplicated...

5. maybe M$ even encouraged these practices because of the perceived advantage for in-house applications vs. third party ones?

[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?

[golergka]

That's a direct action against the interest of their employer, and an attempt to enrich themselves at the benefit of Microsoft. They are purposefully writing bad software which drives ME market share and reputation among developers down only to sell some books.

[Sharlin]

Except if MS gets a share of the profits… which it did in many cases, being the publisher. They had no competitors, there weren't any concerns about market share or reputation!

[incrudible]

There may not have been any concerns at the time, but the damage to the reputation is real, albeit difficult to measure. Nevertheless, you can see that Windows only ever seems to lose market share. Windows desktop is shrinking, Windows mobile is dead, Windows embedded is phasing out, and Windows server is only used for the bare necessities. You can argue that Microsoft successfully managed to pivot to cloud, but that is a rather shallow moat.

[Sharlin]

Among all other variables affecting the market share of Windows, the effect of the inscrutability of the Win32 API is almost certainly negligible. Especially given that as far as I know, their APIs designed in the past 20 years haven't typically been as horrible.

[samus]

Microsoft had no real competition back then, and in their core business (desktop and office) is still quite uncontested. Alternatives to parts of the Windows, MS Office, and various corporate systems exist, but nobody offers the complete package. Extensions to their platform were never required to be perfect, just good enough that being ubiquitous (thanks to the platform) is enough to sell it.

Also, is it really against the interest of their employer to create products that lock in customers and make it harder to migrate away? Creating a market for support and customization, with MS sitting at the source of the knowledge and being able to sell crumbs by printing books and other training materials, and offering training and certification courses?

[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.