Why is documentation so terrible these days?

I’m recovering from ankle surgery after a low speed skiing accident that I had in February, and have decided to take the opportunity to port our Surface Level to Windows Phone 8.1 that I wrote while recovering from the initial accident.

I have about 8 weeks where I’m unable to drive, so will be working from home and very bored, so as a result, will have plenty of time for the project.

One of the things I’ve noticed both for my apps, and my job is that the documentation supplied by companies these days appears to be getting worse.  For instance, in my day job, I’m currently building an embedded system based on an STM32F4 microcontroller, and hooking it to a variety of WIFI modules on the market (the only reason for the variety is we keep coming to problems that aren’t documented, and then prevent us from using a particular module in our product).

I’m not sure if the documentation is intentionally bad so that competitors can’t find the weaknesses, or if the product is bad because it’s rushed to market, or if it’s just pure incompetence.

So, back to Surface Level.  While building the Windows Phone 8.1 version, I added back some code from the working Windows 8.1 version, including an AppBar

 

A quick check of the docs shows it works, but then when I run the program I get this:

A first chance exception of type 'Windows.UI.Xaml.Markup.XamlParseException' occurred in SurfaceLevel.WindowsPhone.exe

WinRT information: Cannot create instance of type '%0' [Line: 17 Position: 17]

Additional information: The text associated with this error code could not be found.

Well, that’s a helpful message.  Line 17 does in fact have this on it:

<AppBar x:Name="BottomBar" Opened="OnOpened">

But position 17 is at x:Name?!

If you do manage to get all the way down the page in the online version of the documentation, you might find this:

Oh, I see.  I can’t use it.

Then I tried to mirror the front camera, like I do on the Windows 8.1 version, like this:

mediaCaptureMgr.SetPreviewMirroring(selectedDeviceInformation != null ? (selectedDeviceInformation.EnclosureLocation.Panel == Windows.Devices.Enumeration.Panel.Front) : false);

That throws an exception, because the phone camera doesn’t support it (at least not on my phone), and there’s some helpful documentation in the remarks section:

Horizontal mirroring is useful for video conferencing or video chat applications, because the users typically want to see a reflected image of themselves. The non-mirrored view can look strange, because we are used to seeing ourselves in a mirror.

To mirror the preview video, apps should instead use the following method. Windows Store apps using JavaScript should use the msHorizontalMirror property of the video object. Windows Store apps using C++, C#, or Visual Basic should use the FlowDirection property on the CaptureElement.

SetPreviewMirroring can potentially be used as a performance optimization on some devices

So, we have a method that we shouldn’t use.

While the information is there, it takes at least 20 minutes to discover why things aren’t working by poring over the documentation for each and every method/function call, and my first language is American English.  I feel really sorry for people who aren’t native speakers.