PowerShell documentation stubs: frustrating for users

I’ve been writing a piece on PowerShell, Microsoft’s generally excellent scripting and automation platform. PowerShell is also largely open source, in its cross-platform, PowerShell Core guise.

Of course I went straight to the official documentation as part of my research. Looks good; but I was puzzled. I would find a promising topic like Object Pipeline, which says:

In this chapter, we will describe how the Windows PowerShell pipeline differs from the pipelines of most popular shells, and then demonstrate some basic tools that you can use to help control pipeline output and also to see how the pipeline operates.

Then I clicked around to read the chapter, and struggled to find the content.

Eventually I figured out the problem, by going to the GitHub repository for the documentation. This content is not yet written. Microsoft’s JuanPablo Jofre has written stubs, either with the intention of completing them later, or perhaps in the hope that the community will step up and help.

Open Source is great, but the user experience of finding stub documents in official documentation, that is not clearly marked as such, is frustrating.

I do not recall this kind of issue in Microsoft documentation written in the old closed-source world, which makes me wonder if the documentation team is under resourced – though the most important part of the documentation, the cmdlet reference, is pretty good in my experience.

My view of PowerShell is that it is now a critically important part of the Microsoft platform. It is not only a tool for managing Windows Server, but also for Microsoft’s online services such as Office 365, Azure Active Directory and other Azure services.

It is worth getting the documentation right.

Windows S: another go at locking down Windows, but the Store is not ready and making it ready is a challenge

There were two big ideas behind Surface RT and Windows RT, the 2012 Windows 8 project which left Microsoft (and some OEM partners) with a mountain of unsold hardware. One was to compete with iPads and Android tablets by making Windows a touch-friendly operating system. The second was that Windows had to move on from being vulnerable to being damaged or completely broken by applications. Traditional Windows applications have installers that run with full admin rights and there is nothing much to stop them installing files in the wrong places, setting themselves to start up automatically, or bloating the Registry (the central configuration database in Windows). “My PC is so slow” is a common complaint, and the cumulative effect of successive application installs is one of the key reasons. Vulnerability to malware is another problem, and one which anti-virus software can never solve completely.

Windows RT solved these problems by disallowing application installs other than via the Windows Store. At that time, Windows Store apps were also locked down, so that a malware infection was only possible if there were a bug in the operating system.

Why did Surface RT and Windows RT fail? The ARM-based hardware was rather slow, which was one of the issues, but a more serious flaw was the lack of compelling applications in the Store. Why was that? Complex reasons, but the chief one is that Windows RT was caught in a cycle of failure. Developers want to make money, and the Windows 8 Store was not sufficiently popular with users to give them a big market. At the same time, users who tried the Store found few applications worth their time, and therefore rarely used it.

The problem was compounded by the unpopularity of Windows 8, which was an unfamiliar environment for the existing Windows users who formed the primary market.

Nevertheless, the thinking behind Windows 8 and Windows RT was not completely off the mark. If only it could get over the hump of unpopularity and lack of apps, it could usher in a new era of Windows devices that were secure, touch-friendly, and resistant to performance decay.

It never did, and with Windows 10 Microsoft appeared to give up. The desktop was back, mouse and keyboard was again primary, and Store apps now ran in windows on the desktop. A special Tablet Mode attempted to make Windows 10 equally as touch-friendly as Windows 8, but did not succeed.

Windows still has those problems though, the ones which Windows RT was intended to solve. Could there be another approach which would fix those issues but in a manner more acceptable to users?

image

Windows S and the Surface Laptop, announced today in New York, is the outcome. It is still Windows 10, but Microsoft has flipped a switch that enforces all apps to be installed from the Windows Store. This switch is already in the latest version of Windows 10, the Creators Update, but off by default:

image

Microsoft has also taken steps to make the Store more attractive for developers. It is no longer necessary to develop apps on a new platform within Windows, as it was for the Windows 8 Store. Now you can simply take your existing desktop application and wrap it to enable Store download. This feature is called the Desktop Bridge, or Project Centennial. Applications so wrapped are not as secure as Windows 8 Store apps were; they can write to files anywhere that the user has permission. At the same time, Microsoft has taken steps to make Desktop Bridge apps better isolated than normal desktop applications. You can read the details of how this works here. It is arranged that applications install all files to a private location, instead of system locations, and that Windows hides this fact from the application code by using redirection. The same is true of the registry. This approach means that file version problems and registry bloat are much less likely. Such issues are still possible because the Desktop Bridge does not redirect file or registry calls outside the application package; these are allowed if the user has permission, for compatibility reasons. Nevertheless, it is a big advance on old-style Windows desktop application installs.

When the user removes a Desktop Bridge application, in most cases all its files and registry entries are cleanly removed.

An important additional protection is that applications submitted to the Store are vetted by Microsoft, so malicious or badly behaved instances should not get through.

Windows S will be installed by default both on Surface Laptop and on a new generation of low-end laptops aimed mainly at the education market.

The benefits of Windows S are real; but unfortunately Microsoft still has not solved the Store problem. Currently, your favourite Windows applications are not in the Store. Microsoft Office will be there, thanks to the Desktop Bridge, but many others are not.

image

Microsoft’s big bet is that thanks to Windows S and other initiatives, the Store will be sufficiently attractive to developers, and sufficiently easy to target, that it will soon offer a full range of applications including all your favourites.

Right now though, if you get a Windows S laptop, you will probably end up buying the upgrade to Windows 10 Pro, for $49.00 or equivalent. Then you can install any Windows desktop application. However, by doing so you make it unnecessary for developers to bother using Desktop Bridge to wrap their applications – so they might never do so.

Windows S has a few other limitations:

Microsoft Edge is the default web browser on Microsoft 10 S. You are able to download another browser that might be available from the Windows Store, but Microsoft Edge will remain the default if, for example, you open an .htm file. Additionally, the default search provider in Microsoft Edge and Internet Explorer cannot be changed.

In addition, it cannot join a local Windows domain (a problem for many businesses), though it can join Azure AD, the Office 365 directory.

Microsoft’s goal here is worthwhile: to move Windows into a new place in terms of security and resilience. Getting it there though will not be easy.

Xamarin Challenge shows bumps in Microsoft’s path to cross-platform mobile

Microsoft ran a Xamarin Challenge over on Paul Thurrott’s site. The idea was to demo how to build a cross-platform mobile app with Microsoft’s cross-platform mobile toolkit.

The challenge was in three steps. You build a weather app, complete with crash analytics on the Visual Studio Mobile Center.

image

Someone did a lot of work on this, and the app looks pretty and works nicely once you get it running.

Despite this, I am not sure that the challenge was altogether successful. It is a step-by-step which in theory involves no developer expertise as you simply copy and paste code into your project. I am not sure that is the best way to learn, but that is by the by. I doubt that learning how to code for Xamarin was the primary goal of the challenge. I’d guess it was more about showing how easily you can build a cross-platform app (Android, iOS and Windows UWP) using Xamarin, C# and Visual Studio 2017.

Well, in fact a little bit of developer expertise was required to complete the challenge, because the step by step instructions did not quite work (in my experience). I did not make a note of all the times I had to do something not in the given steps, but there were many occasions, the main issues being around using the Visual Studio Android emulator, NuGet package management, and a few small tweaks to the code itself. The code as given made no allowance for the cloud services it called being offline, or the connection to the internet not being available, but would simply crash in this case.

The challenge could be an excellent resource for Microsoft and Xamarin if the company drills down into the problems developers experienced trying to complete the challenge, recorded in this forum thread. Here are a few examples:

Myself and 5 other developers in our office attempted the challenge and none of us have been able to get past the first challenge. We are not Microsoft Visual Studio experts so we had hoped following the provided instructions would be sufficient.

The upload was failing on a discrepancy between 2 different versions of the Json package, which somehow had crept into the project. Installing over 40 updates in Nuget resolved this.

Many thanks for running this challenge –this was very useful and worthwhile. I just wish modern development did not feel like trying to dance on a mile high stack of chairs with a leg missing on the bottommost one!

I got a late start on the challenge and was able to complete part 1 pretty quickly but was only able to run the UWP locally. I cannot seem to get either the Windows mobile emulator or Android emulators to run successfully. I can’t deploy to the Window Mobile emulator, it returns an error indicating the emulator failed to start. As for the Android emulator, it launches, but the emulator does not have a connection to the network, so the application encounters an exception.

Note that those posting to the forum were more likely to be the ones with problems; there could in theory be many others who breezed through without any issues. But as one participant writes, “I’d be interested in what percentage of participants actually got to the end of the challenge with no problems.”

I like Xamarin; it does an amazing job in enabling cross-platform development with C# and it would be my tool of choice for cross-platform mobile development. It is not always straightforward though, and the kinds of issues experienced by the challenge participants illustrate what can go wrong.

If you just use the native toolkits, such as Android Studio and Xcode, you will have a smoother experience, but of course miss out on the productivity benefit of cross-platform code. That is the trade-off you make.