Technical Writing

Welcome to IT Writing. This site is edited by Tim Anderson, a techncal journalist. Here you will find comment, articles and reviews on a variety of subjects. A few words of guidance on navigating the site:

  • On the home page you will find posts relating to professional technology.
  • Consumer technology is covered in the Gadget Writing section on the top menu.
  • Occasional posts about music are found in the Music Writing section on the top menu.
image

Hands On ASP.NET Core

I’ve been putting together a quick web application (well, I thought it would be quick) in my spare time (hah!) and I picked ASP.NET Core on Linux as a sensible option given that I like working in C#. Overall it has been a reasonable experience so far and I still love the language. This is the most extensive work I have done so far with ASP.NET Core though and I have a few observations.

It is not a difficult framework to work with but I believe it could be made more approachable. This is largely a matter of documentation though another point of confusion is the transition Microsoft has been making from ASP.NET MVC to Razor Pages. These two frameworks are similar but different, they share a lot of technology but some things work in one but not the other, and sometimes it is not clear whether what you are reading applies just to ASP.NET MVC, or just to Razor Pages, or to both, or to both but with a little tweaking to account for differences. I started with MVC because I am more familiar with it but have shifted to Razor Pages because that seems to be the preferred direction; really I am equally happy with either.

If you are thinking of getting started with ASP.NET Core I recommend you start not with the framework, but with making sure that you are familiar with the following topics:

Dependency injection. If you are puzzling about something in the framework the answer may be “add it to the constructor and it magically works.” This is obvious if you are familiar with it but not otherwise.

Anonymous types. These seem to crop up quite a lot.

Lambdas and the arrow operator =>

LINQ queries

Now, the documentation. Unless you have perhaps found a good and up to date book you will probably start here.

image

Now, I do think there are lots of good things about docs.microsoft.com, the fact that it is all on GitHub and open for comment and improvement, the fact that it performs well, and the obvious effort that has gone into many of the topics.

That said, I do not much like this page. My biggest problem with it is that there is no simple link to a comprehensive reference. It is a bunch of little tutorials which may or may not tell you what you need to know. It gets better if you click into one of the topics and I like this page, for example, much better, with the hierarchical list of topics on the left.

image

It is still not great though. There is a big emphasis on tutorials, and while I agree that learning through doing is a great way to learn, the problem with the tutorials is that they tend to leave you with lots of questions and no obvious route to answers.

I will give you an example. I decided to use the ASP.NET Identity system in my application, because it saves a ton of tedious work doing registration, password reset, login, and so on, plus it is security-critical code that I would likely get wrong if I did it myself.

The problem you will immediately hit though is that you want to store additional data about users. This could be any kind of data but let’s call it additional profile data. For example, you want to let users upload an image which is then displayed in the application. There are some heavy articles about customizing identity but thee is also this one on adding custom user data to an ASP.NET Core web app. It’s great but it does not actually tell you how to retrieve the custom user data in your application. Eventually I figured out a way of doing it. You just have to use dependency injection to get an instance of the UserManager class. So you pop this in the constructor for one of your classes:

UserManager<YourCustomUser> UserManager

and store it in a private variable. Then you can do:

var MyTask = _userManager.GetUserAsync(User);
MyTask.Wait();
var MyUser = MyTask.Result;

or something similar (if it is a synchronous method) and it just works.

Let me add something else. The actual API reference for ASP.NET Core is almost useless. It faithfully documents each class and method while often saying nothing about how or why to use it.

Data access

My application is really forms over data as so many are, so data access plays a big role. There seem to be plenty of tutorials on data access in the ASP.NET Core documentation but I don’t much like them. The problem is Entity Framework. Most of the documentation assumes it. It is not that Entity Framework is bad; it does seem to work well and while there is debate about how well it performs, in many cases it does not matter, and in other cases you can fine-tune it. My problem rather is that what Microsoft calls a “complex data model” is actually the normal case, where you have many-to-many relationships, and dealing with this in Entity Framework soon gets fiddly. I am guilty of lacking patience, but being familiar with SQL it is easier for me just to write the SQL and to know exactly what data is being saved and what data is being retrieved. I have left Entity Framework in place because the Identity system uses it (and it looks non-trivial to replace) but for the rest I have migrated to Dapper which seems ideal. It is not a full-featured ORM and it expects you to write the SQL but does a lot that saves time. My only complaint about Dapper is that (again) the documentation isn’t great but I’ve found it much simpler to grok than the more advanced aspects of Entity Framework.

One thing I do like about Entity Framework is data migrations. Like most developers I have a local database and another one online and code-first data migrations save a lot of work creating database tables and keeping the schema in sync. Dapper does not have this.

StackOverflow

Of course it is true that no matter what is your question, someone has asked it before, and often the best place to find the answer is on StackOverflow. Big appreciation for the folk who take the time to answer questions there, though I’d add that it is not a place from which to copy code, it is a place to understand a solution. Out of date information is a problem, as it is in Microsoft’s own documentation.

Finally

I think ASP.NET Core is a great framework (or frameworks) but not as approachable as it could be. Documenting it in the best way is not an easy problem to solve, and every developer comes with different skills and requirements. Perhaps Microsoft could get someone suitable to write a nice book aimed at intermediate coders, and one that does not assume you want to use Entity Framework. Then offer it as a free download and/or publish it online as part of the documentation, and keep it up to date as new versions appear.

Android: a lack of software to take advantage of high-end mobiles?

I’ve got an pre-release version of Oppo’s Find X2 smartphone for review. It’s a great device and with an outstanding camera. I reviewed it for The Register here.

image

In preparing the review I asked a few people what they would like in a high-end android mobile. Things like an excellent display, fast performance, strong camera and plenty of storage all get mentioned, but then I see people spending most of their time on social media and wonder if even mid-range mobiles are perfectly good enough for the average user. 5G has huge potential (and the Find X2 is a 5G device), but coverage is limited, you will pay the operator quite a bit more, and arguably it needs to reach a tipping point where enough people have it that we can design new applications to take advantage; until then, it’s nice to have faster internet but not game-changing.

Notably missing from our Find X2 press briefing was any demonstration along the lines of “you should see the amazing performance on application x”, where application x is something familiar rather than a benchmark. Gaming is one area where faster hardware does make a difference, having said which, Android and iOS still tend to be the home for casual games and a mobile platform can never compete with the monster GPUs you can plug into a desktop or even a gaming laptop. Unless you stream the games, and shift the need for intensive compute power into the cloud.

Local storage? Handy for a video library to play on a train or flight, or for audiophiles to store huge files full of arguably inaudible data, but for most of us cloud storage makes a local storage less important once it is enough. What is enough? Probably less than the 512GB on the Find X2. It is nice to have, say for capturing 4K video without anxiety, but a lot of people simply do not need to think about how much storage they have once it is beyond 128GB or so.

Photography remains a key feature and one where local compute power does make a big difference – since mobile cameras are as much about digital processing as about optics. I would argue though that one of the reasons vendors have got carried away with multiple lenses and amazing capabilities in mobile cameras is that it remains an area where useful improvements are attainable – perhaps beyond the importance of these improvements to most users. As with gaming, there is a problem in that actual cameras will always be preferable to the camera in a smartphone, for the best results, though the great thing about smartphones is that they are always in your pocket.

The question then: could there be another wave of software that will make the hardware on a modern high-end smartphone more desirable?

Another way of putting is is that it is software, not hardware, that will radically improve smartphones, which explains the lack of excitement around today’s big releases.

Annoying Azure capacity problems in UK West region

I have a test setup of Windows Virtual Desktop (WVD) and was experimenting with adding an additional VM. At least, I tried to. My WVD virtual network is in the UK West region. And when I try to create a VM I get the message: Your subscription doesn’t support virtual machine creation in UK West. Choose a different location.

image

This was annoying because my WVD virtual network is in UK West, so no, another region would not do. If you click Learn More you get this page which says that if you get this message and still want to deploy a VM in the region, you have to raise a support case.

I am guessing but I presume this is a capacity problem and that Microsoft is discouraging VM creation in the region. The problem for the customer is that such things are opaque; there is nowhere you can see which Azure regions are running close to capacity.

Five facts about Rust

Rust is a programming language aimed at system programming – for which high performance and low-level system access is essential – but with safety features that make it harder to write dangerous or insecure code (though it is still possible). Since all programmers value both speed and stability, Rust is being used for tasks other than system programming as well. Rust is open source and sponsored by Mozilla, which uses Rust in its own development including parts of the Firefox web browser.

Rust is not one of the most-used programming languages; according to a StackOverflow survey only 3.2% of developers use it. Among professional developers that figure drops to 3.0%.

Yet Rust comfortably tops the list of most loved languages.

image

Second, Rust has built-in support for unit tests, in conjunction with Cargo, the Rust build system and package manager. Cargo will both generate test functions and run tests for you. You can do unit tests in any language, but this is a great way to prompt developers to use them.  Tests are a big deal. I recall Sqlite developer Dr D Richard Hipp telling me that testing was core to the project and without it, it could not progress as it does. Sqlite has 662 times more test code than the code in the Sqlite library itself.

Third, Rust can be compiled to WebAssembly so you can run it in a web browser.

Fourth, Microsoft is considering using Rust on the basis that it “could eliminate an entire class of vulnerabilities before they ever happened”.

Fifth, work is under way to build a new operating system with Rust, called Redox. I wrote about this briefly for the Register.

If asked to think of a language that is as efficient and powerful as C++ but nicer and for many of us more productive to use, I think of Delphi (or Object Pascal). Delphi has an ardent niche following but is unlikely to grow its usage much beyond it. Rust on the other hand is a modern language that benefits from things we have learned about programming in the last forty years (C++ was first thought by Bjarne Stroustrup when writing his PhD thesis, though the name dates from 1983), and with a refreshing lack of legacy. And Delphi is not open source, unless you mean Lazarus.

Worth a look if you have a moment – see here for how Verity Stop got on.

The problem with price comparison sites

A piece in the weekend Guardian by its excellent personal finance correspondent Patrick Collinson includes, almost as an aside, an explanation of why price comparison sites are bad news for some customers.

Collinson’s report concerns a man who discovered that his elderly parents-in-law were being asked for £579.08 for home insurance from the Halifax. He considered this excessive, went online to get a quote direct from Halifax for the same house, and was quoted £108. In other words, the renewal was more then five times more expensive, a shocking penalty for loyalty or inertia.

Why is this happening? In part, because insurance companies can get away with it, but that is not the whole story. The problem, Collinson explains, is the price comparison sites which “drive nearly all new business.”

It is obvious that price comparison sites tend to increase prices, since they are financed by commission on sales made through the site. This effect in itself will not make such a dramatic difference though. The bigger problem is that in order to secure the sale, prices for new business have to be cut to the bone. The only viable way to quote such low prices is to subsidise new customers with profits made from existing customers.

That does not justify the behaviour of the Halifax, which actually increased the premium demanded from this elderly couple by £96.52 from that asked the previous year. But it does show why these sites tend to increase unfair pricing.

Microsoft posts another strong set of results, does not know how to invest its profits

Microsoft has announced its quarterly financial statements, reporting revenue of $33.1 billion, up 14% on the same period last year (though fractionally down on the previous quarter).

It does not know how to invest the money it is making. It returned $7.9 billion to shareholders via dividends and buybacks.

What’s notable? The fastest-growing business is Azure, with revenue up by 59%, followed by Dynamics 365 up by 41%.

Office 365 commercial revenue up by 25%, Dynamics 365 up by 41%.

Microsoft notes that it is achieving “higher average revenue per user” on Office 365, indicating some success in adding premium features.

LinkedIn is performing well, revenue up by 25%.

Xbox hardware revenue is down by 34%, but gaming revenue overall down by only 7%. The next hope for gaming will be when the next generation of Xbox appears, Project “Scarlett”, expected this time next year.

In Windows. business revenue is up in both “commercial revenue” (Microsoft 365 and other license sales) and OEM Pro revenue (PCs with Windows 10 Pro installed). However consumer Windows is down 7%. Microsoft says “pressure in the entry level category”, but my guess is that home PCs are just not being replaced and that Chromebooks and iPads are eating into laptop sales.

Quarter ending Sept 30th 2019 vs quarter ending Sept 30th 2018, $millions

Segment Revenue Change Operating income Change
Productivity and Business Processes 11077 +1306 4782 +901
Intelligent Cloud 10845 +2278 3889 +958
More Personal Computing 11133 +387 4015 +872

The segments break down as:

Productivity and Business Processes: Office, Office 365, Dynamics 365 and on-premises Dynamics, LinkedIn

Intelligent Cloud: Server products, Azure cloud services

More Personal Computing: Consumer including Windows, Xbox; Bing search; Surface hardware

Xcode on Catalina update hassles

I have a Mac running Catalina. It is almost new and I did not migrate anything from the old Mac, so should be a very clean install.

I installed Xcode 11 from the App Store. All fine.

Yesterday it wanted to update to Xcode 11.1. But the update took a long time and then failed. Try again later. I did. Same. The App Store UI gives you no clue what is not working.

I ran the Console app to check the log. Install failed “The package is attempting to install content to the system volume.”

Annoying. Suggested fix is to download the DMG. Another idea is to uninstall and then reinstall from the App Store. I like having it App Store managed so I did the latter and it worked.

Together with Gimp permission problems it looks like permission issues in Catalina are a considerable annoyance. Which is OK if security is better as a result; but that does not excuse this kind of arbitrary behaviour.

Just ahead of the launch of Oppo Reno 2, here is a look at Oppo Reno 10x Zoom

Oppo will launch Reno 2 on 16th October, under the heading “Make the world your studio”. Oppo mobiles have been making a an impression as an example of high quality technology at a price a bit less than you would pay for a Samsung or a Sony – similar in that respect to Huawei, though currently without the challenge Huawei faces in trying to market Android devices without Google Play services.

Oppo is a brand of BBK Electronics Corp, a Chinese company based in Chang’an, Dongguan. Other BBK Electronics brands include OnePlus and Vivo. If you combine the market share of all these brands, it is in the top four globally.

My first encounter with the Reno brand was in May this year when I attended the launch of the Reno 10x Zoom and the Reno 5G (essentially the 10x Zoom with 5G support) in London. Unfortunately I was not able to borrow a device for review until recently; however I have been using a 10x Zoom for the last couple of weeks and found it pretty interesting.

image

First impression: this is a large device. It measures 7.72 x 16.2 x 0.93cm and weighs about 215g. The AMOLED screen diagonal is 16.9cm and the resolution 2340 x 1080 pixels.

Second impression: it takes amazing pictures. To me, this is not just a matter of specification. I am not a professional photographer, but do take thousands of photos for work. Unfortunately I don’t have an iPhone 11, Samsung Galaxy Note 10 to test against. The mobile I’ve actually been using of late is the Honor 10 AI, a year older and considerably cheaper than the Reno but with a decent camera. I present the below snaps not as a fair comparison but to show how the Reno 10x Zoom compares to a more ordinary smartphone camera.

Here is a random pic of some flowers taken with the Honor 10 AI (left) and the Reno 10x Zoom (right):

image

Not too much in it? Try zooming in on some detail (same pic, cropped):

image

The Reno 10x Zoom also, believe it not, has a zoom feature. Here is a detail from my snap of an old coin at 4.9x, hand-held, no tripod.

image

There is something curious about this. Despite the name, the Reno has 5x optical zoom, with 10x and more (in fact up to 60x) available through digital processing. You soon learn that the quality is best when using the optical zoom alone; there is a noticeable change when you exceed 5x and not a good one.

The image stabilisation seems excellent.

The UI for this is therefore unfortunate. The way it works is that when you open the camera a small 1x button appears in the image. Tap it, and it goes to 2x.Tap again for 6x, and again for 10x. If you want other settings you either use pinch and zoom, or press and hold on the button whereupon a scale appears. Since there is a drop-off in quality after 5x, it would make more sense for the tap to give this setting.

There are four camera lenses on the Reno. On the rear, a 48MP f/1.7 wide, a 13MP f/2.4 telephoto, and an 8MP f/2.2 ultra-wide. The telephoto lens has a periscope design (like Huawei’s P30 Pro), meaning that the lens extends along with the length of the phone internally, using a prism to bend the light, so that the lens can be longer than a thin smartphone normally allows.

image

There is also a small bump (surrounded by green in the pic below) which is a thoughtful feature to protect the lenses if the device is placed on a flat surface.

image

On the front is a 16MP f/2.0 sensor which also gives great results, excellent for selfies or video conferencing. The notable feature here is that it is hinged and when not in use, slides into the body of the camera. This avoids having a notch. Nice feature.

image

ColorOS and special features

We might wish that vendors just use stock Android but they prefer to customize it, probably in the hope that customers, once having learned a particular flavour of Android, will be reluctant to switch.

The Oppo variant is called ColorOS. One good thing about it is that you can download a manual which is currently 335pp. It is not specific to the Reno 10x Zoom and some things are wrong (it references a non-existent headphone jack, for example), but it helps if you want to understand the details of the system. You might not otherwise know, for example, that there is a setting which lets you open the camera by drawing an O gesture on the lock screen.

image

How many customers will find and read this manual? My hunch is relatively few. Most people get a new smartphone, transfer their favourite apps, tap around a bit to work out how to set a few things as they want them, and then do not worry.

If you have a 10x, I particularly recommend reading the section on the camera as you will want to understand each feature and how to operate it.

The Reno 10x does have quite a few smart features. Another worth noting is “Auto answer when phone is near ear”. You can also have it so that it will automatically switch from speaker to receiver when you hold the phone to your ear.

Face unlock is supported but you are not walked through setting this up automatically. You are prompted to enrol a fingerprint though. The fingerprint sensor is under glass on the front – I prefer them on the rear – but there is a nice feature where the fingerprint area glows when you pick up the device. It works but it is not brilliant if conditions are sub-optimal, for example with a damp hand.

The Reno 10x Zoom supports split screen mode via a three-finger gesture. With a large high-resolution screen this may be useful. Here is Microsoft Teams (Left) with a web browser (Right).

Screenshot_2019-10-13-12-20-18-33_3aea4af51f236e4932235fdada7d1643

Settings – Smart services includes Riding mode, designed for cycling, which will disable all notifications except whitelisted calls.

VOOC (Voltage Open Loop Multistep Constant-current Charging) is Oppo’s fast charging technology.

Dolby Atmos audio is included and there are stereo speakers. Sound from these is nothing special, but sound from the bundled earbuds is excellent.

Quick conclusions

A Reno 10x Zoom is not a cheap smartphone, but it does cost less than the latest flagship devices from Apple or Samsung. If you are like me and need a great camera, it strikes me as a good choice. If you do not care much about the camera, look elsewhere.

Things I especially like:

  • Excellent camera
  • No notch
  • Great audio quality though supplied earbuds
  • Thoughtful design and high quality build

There are a few things against it though:

  • Relatively bulky
  • No wireless charging
  • No headphone jack (less important now that wireless earbuds are common)

Spec summary

OS: Android 9 with ColorOS 6

Screen: AMOLED 6.6″ 2340 x 1080 at 387 ppi

Chipset: Qualcomm Snapdragon 855 SM8150 , 8 Core Kryo 485 2.85 GHz

Integrated GPU: Qualcomm Adreno 640

RAM: 8GB

Storage: 256GB

Dual SIM: Yes – 2 x Nano SIM or SIM + Micro SD

NFC: Yes

Sensors: Geomagnetic, Light, Proximity, Accelerometer, Gyro, Laser focus, dual-band GPS

WiFi: 802.11 a/b/g/n/ac, 2.4GHz/5GHz, hotspot support

Bluetooth: 5.0

Connections: USB Type-C with OTG support.

Size and weight: 162 mm x 77.2 mm  x 9.3 mm, 215g

Battery: 4065 mAh. No wireless charging.

Fingerprint sensor: Front, under glass

Face unlock: Yes

Rear camera: Rear: 48MP + 8MP + 13MP

Front camera: 16MP

Finding the multi-factor authentication and authenticator options in an Office 365 account

Microsoft has done some good work enabling and promoting multi-factor authentication in Office 365, including use of the Microsoft Authenticator app.

Strangely though, it has made the user settings for this hard to find.

Logically it should be in the My Account – Security and Privacy section, but it is not.

image

Where is it then? The easiest way to find it is here:

https://aka.ms/mfasetup

image

Saving documents in Office 365 desktop applications

Those readers who also follow The Register may have noticed that I am writing more for that publication now, though be assured that I will still post here from time to time. My most recent piece is on saving documents in Office and reflects a longstanding annoyance that in applications like Word and Excel Microsoft mostly bypasses the standard Windows file save dialog in favour of its own Backstage,  now supplemented by an additional dialog which the team says  will help us “save your files to the cloud more easily.”

image

Admittedly the new dialog is small and neat relative to the cluttered Backstage but it is not very flexible and if you use multiple sub-folders to organize our files you will be clicking More save options half the time, defeating the point.

There is also a suspicion that rather than helping us with something most of us do not need help with, Microsoft is trying to promote OneDrive – which it is entitled to do, but it is an annoyance if the software you have paid for is being used as a surreptitious marketing tool.