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

Reimagining Collaboration by Phil Simon

This is a book about collaboration in the new era of Zoom, Teams, Slack and other such tools – not that they are completely new, but the pandemic and enforced remote working caused a huge boom in usage and some permanent changes in the way people work together. Author Phil Simon is a US specialist in business communications, and associated with the Agile methodology of software development – quite appropriate for this book, since collaboration is at the heart of Agile.

There are a few themes here. Simon believes that organisations need strong collaboration in order to thrive, and personally I think that is spot on. He spends some time distinguishing between collaboration and other related but different things like communication (a pre-requisite but insufficient on its own), or co-operation which can be a passive relationship; people can co-operate without actually collaborating.

Despite all the this, the main topic of the part 1 of this book, I am not sure that Simon ever nails what collaboration really is, at least not in this book. He has a go at it and there are many examples given of what it is not, but it remains, in my mind, a bit elusive. I did like his metric of organizational health: “The ability to rally around a common vision, execute effectively, and create a culture of innovation.”

Simon does show a good understanding of the human factor in productivity. He talks about managers versus makers, and how managers feel the need to communicate often with many people, while makers need to reduce distraction and focus on a task; I am not sure if he had software development in mind but this is a good description of what developers need.

Part 2 then gets to the heart of the book: better collaboration through technology. The key concept Simon uses is what he calls a “collaboration hub,” meaning any of a number of tools which form a central internet-connected space where users can interact with one another. This includes what the author calls the big three, Slack, Teams and Zoom, as well as other applications such as Expensify or Canva.  

The author is a user of Slack and of Google Docs and while he shows a commendable neutrality in the sense that he considers other tools such as Teams equally effective, adding that “It’s fair to call the similarities around today’s internal collaboration hubs remarkable,” his greater depth of knowledge of the tools he mainly uses does show. There is really much more about Slack than about Teams, and that is something to be aware of. Teams users can still benefit from the book but less so than Slack users.

There is a big theme here though which is that the author considers email, especially internal email, a blocker to collaboration. He gives reasons, including that inboxes tend to die when an individual leaves the company; that email is gaffe-prone since a careless email, or a careless reply-all, cannot be unsent; and that emailing attachments like spreadsheets leads to multiple forks of the same data. In fact, toward the end of the book Simon remarks that “Effective, long-term collaboration cannot take place via email. Period.” He also recommends ditching internal email completely.

While I have some sympathy with this view, I think it is overdone. I reminded myself that one of the most successful collaborative projects of all time, the Linux kernel, is based on email lists. 

Still, Simon is quite correct, a collaboration tool with channels for team members has lots of advantages over email, gathering all the communications in one spam-free place and making search much easier.

Part three of the book is called “moving from theory to practice” and contains lots of discussion about how organizations can move towards using collaboration hubs and what can go wrong. Then part four peeks into the future and envisages smarter collaboration hubs which use AI to book meetings for us, automatically transcribes meetings and sends automatic alerts to Slack channels.

There is plenty of wisdom though I could have done with more on practical questions about how to get the most from Slack or Teams. How many channels or Teams should you have? When should you have a video conference versus a message chat? Should we have our collaboration hubs always open or sign out sometimes? Who should be able to create a channel, or should anyone? And what more advanced or intricate features of the products are worthwhile?

I enjoyed Simon’s willingness to be blunt at times, as well as some amusing reflections like “In my consulting days, I often saw project managers call meetings essentially because they were bored.”

Towards the end of the book we also get this: “Just because the discussion or task takes place in a hub doesn’t mean that it’s truly collaborative.” I agree. What then is the magic that enables an organization to be collaborative? In the end it is corporate culture rather than tools that matter most. I think the author recognizes that, but after reading the book, I am still not clear about the best way to get to the collaborative culture to which we should aspire.

Thanks to Netgalley for an electronic review copy of this title

Web page memory usage: how much is too much?

I have a web application that loads names into a picklist and the question came up: how many names would be too much for the web page to handle? What about 5,000 names, for example?

Modern web browsers have a memory snapshot built in. Just press F12 and there it is. So I fired up my application with over 5,000 names loaded into an array and displayed in a scrolling div. 2.5 MB.

Then I visited Facebook. Logged in, the page reported over 78 MB.

image

Google’s clean-looking home page? Not logged in, 11.2 MB.

image

Twitter? Logged in, 83 MB.

image

This was enough for me to stop worrying about the memory impact of 5,000 names in my web application. With our casual acceptance of multi-MB web pages it is easy to forget that the complete works of Shakespeare in plain text is 5.5 MB and compresses to less than half of that.

Just because you can do something, does not mean you should. Smaller is better and faster, and software bloat of various kinds is responsible for many performance issues.

There are trade-offs though both in time and in performance. Maybe it is better to load just a few names, and retrieve more from the server when needed. It is easy to test such things. Nevertheless, I found it useful to get some perspective on the memory usage of modern web sites.

Windows Subsystem for Linux 2 will not start: a possible fix

I find that Windows Subsystem for Linux (WSL) sometimes fails to start after rebooting Windows 11. Once it is up and running it is fine.

Symptoms are that WSL fails to open and the wsl command hangs. VS Code, if set to open in WSL, fails to open the folder.

Rather than rebooting, you can also try the steps here. It is a matter of finding the process id for LxssManager:

tasklist /svc /fi “imagename eq svchost.exe”

then using End Process Tree in the Task Manager Details view for that process ID to terminate it. It will then restart automatically or you can use the wsl command as usual.

Using an M1 Mac after a lifetime of mainly Windows

So I got an M1 MacBook Pro back in April and it is time for a quick brain dump on my experience. I am not travelling as much as I did pre-lockdown, so although I got the Mac as a replacement for an ancient Windows laptop it gets used at home too. My usual desktop PC is a few years old but a decent spec gaming PC withCore i7-7700 3.6 GHz, 16GB RAM and Nvidia RTX 2060 GPU. I have been happy with it; but I do find myself thinking “why not just use the MacBook” when needing to fire up a computer, a subconscious preference that bears examination. Most of my work is writing, web browsing and coding.

I do not particularly prefer the macOS UI to that of Windows. It is more consistent because Apple managed iOS vs macOS sensibly whereas Microsoft made a hash of Windows desktop vs Windows CE vs Windows Phone vs Windows 8 and has now settled on a thing called WinUI but scratch the surface of Windows and you still find UI that has not changed for decades.

I digress though. I do not mind the Windows UI, I am used to it. What I do mind though is annoyances like the always-broken Windows search, and the way certain actions cause lengthy pauses that make me wonder what my PC is doing. In my case, sorting a large directory in Windows Explorer takes an age. Another little issue is that creating a new folder works fine, but renaming it causes a long pause. There also seem to be some focus issues. I create a new folder, I rename it and press Enter. Eventually it renames, but half the time the focus mysteriously switches to a different folder.

I realise that these problems do not occur with a new install of Windows and that I could pop out and buy a Surface laptop and it would be fine. For a bit. Windows, it seems to me, still suffers from the cruft problem beautifully described by Verity Stob 20 years ago. I do not think Macs are completely immune (I had a Mac Mini where I upgraded the OS once too often and it crawled) but does seem to me more resistant.

There is another thing that I like about the MacBook. You close the lid and it sleeps. You open the lid minutes, hours or days later, and it wakes. This has never worked well for me on Windows, though it is meant to do the same. I can believe that it is hard to implement, but when it works it is a huge benefit.

There is also the unwanted advertising that has crept into the Windows UI especially since Windows 11. Working on the MacBook I do notice its absence; I can better focus on what I want to do.

From a developer perspective, the performance of the M1 Pro is a delight. I work mostly in Visual Studio Code on both platforms; even on Windows I have come to prefer VS Code for most types of work. There is also the fact that Unix-like operating systems have won in server and web applications, so there is less friction there.

Launchpad: reminiscent of the Windows 8 Start screen?

Microsoft came up with a great application launcher in the Windows 95 Start menu – and improved it until it reached its peak in Windows 7. I also like the Windows 8 full-screen version. Windows 10 and 11 are not so good though. You get inadvertent web searches, as well as the problem of apps that you search for not appearing for strange reasons. The Mac Launchpad, which reminds me of the Windows 8 full-screen Start menu, seems to work well. You type what you want and all the matches appear.

What do I miss when not using Windows? It is mainly a matter of working out new ways to do certain tasks. I do miss Hyper-V and WSL (Windows Subsystem for Linux) though I have had success with UTM for running both Windows and Ubuntu on the Mac. The integration of WSL with the desktop OS is great though. Microsoft Office still works best on Windows though not to the extent of a few years back. There is no Paint or Notepad, and favourites like Notepad++ do not run natively, but Preview works for cropping images and alternatives to Windows utilities exist.

Sometimes you are pushed towards the command line which is not a bad thing. No WinSCP for example, so use scp instead, and do some helper scripts for common tasks. You end up saving time. (I realise you can script WinSCP as well). And no need for Putty; just type ssh or script the command line you need.

I do expect though to use Windows less in future, and for me that is a big change.

Book review: After Steve by Tripp Mickle

This is billed as a book about a company, but is more accurately described as about two people, Tim Cook and Jony Ive, respectively CEO and former Chief Design Officer at Apple, one of the world’s biggest and most profitable companies. The author Tripp Mickle is a reporter at the Wall Street Journal where he covered Apple for four years.

Mickle has a thesis: that under Cook Apple’s profitability has flourished but its design-led innovation has faltered, damaged in 2011 when co-founder Steve Jobs died at the age of 56. “It’s unclear if design will ever regain its position as the dominant voice over product direction,” he writes. In his epilogue, Mickle says that “Cook’s aloofness and unknowability made him an imperfect partner for an artist who wanted to bring empathy to every product.” The author mentions several times that Cook “seldom went to the design studio to see Ive’s team work.”

The book has amazing detail and represents the outcome of interviews with “more than two hundred current and former Apple employees” supplemented by further interviews with their family members, friends, suppliers of Apple, competitors, and government officials. There is lots of dialogue in the accounts of key incidents, drawn either from recordings or “reconstructed based on the recollections of people familiar with the events described.” As you read, you feel immersed in the company. It is a great achievement, particularly (as the author also notes) considering that “at Apple, current and former employees adhere to a strict code of silence.” There is a thick section of notes and references.

After Steve then is essential reading for Apple watchers. That said, I have a couple of reservations. At 512pp this is a lengthy work and for me, too long. It is occasionally repetitive, the writing is professional but at times pedestrian. Further, if your interest is in Apple the company rather than Cook and Ive, it is overly focused on those two people.

This last point is perhaps why Mickle misses the impact of Apple Silicon, the series of ARM-based processors which began with the A series and took over from Intel as the technology in Mac computers from November 2020 with the launch of the M1. Recently Apple has announced the M2 with claimed performance improvements of up to 18% for the CPU and 35% for the GPU, compared to the M1.

Apple Silicon matters because it dramatically improves over x86 in its power/performance ratio, making the company’s laptops and iPads a delight compared to their competition. It may not be design-based, and it builds on ARM and the work of others, but it is a huge advance and gives the company’s hardware an edge over its Windows and Android competition that is hard to counter. Johny Srouji, in charge of Apple Silicon? Not mentioned by Mickle.

I would have preferred the book to be shorter (though researchers may be glad of its detail). What of its central thesis? Mickle makes the point that Apple Watch has a disappointing lack of focus, which I agree with, and that projects like the Apple electric car appear to have faltered. The Beats acquisition had a mixed outcome, and this was a puzzle to me too. Apple did not need Beats, its culture was alien, and my sense is that Apple Music would have flourished equally well without it.

I do think though that since Jobs Apple has developed something with iPhone-level impact and that is Apple Silicon and the M series in particular. I also think that Mickle misses something of the big picture. Buying a smartphone or computer? There is the Android jungle, or the Windows jungle, or Apple. For many it is hardly a choice; and the fact that this is more than ever true more than a decade after the passing of Jobs is huge credit to those involved and makes the accusation “how Apple became a trillion-dollar company and lost its soul” ring just a bit hollow.

Installing Ubuntu 22.04 on Apple M1 with UTM

I  started with Arch Linux for Linux development  on  M1, which works, but succumbed to Ubuntu just because it is so widely used and therefore easier to find help. It is also supported by VS Code for remote development, as I am aiming for something similar to a WSL setup on Windows and using VS Code on the host side. I had problems installing 22.04 though;  the install completed but trying to boot resulted in:

EFI stub: booting Linux Kernel

EFI stub: Using DTB from configuration table

EFI stub: Exiting boot services

and there it would stay.

The fix I found was to update QEMU:

sudo port selfupdate

sudo port install qemu

after which Ubuntu started without issue (no need to reinstall).

Following this I was able to install and use the Remote – SSH extension in VS Code which worked first time.

Small points to note:

  • I accepted the option in Ubuntu to install the OpenSSH server during installation
  • In UTM I changed the networking for the VM to Emulated VLAN rather than Shared Network, in order to use port forwarding. I forwarded both the SSH port 22 and also the HTTP port 80, to different ports on the Mac, so that I can test web applications running on Ubuntu.

Thanks also to Liz Rice for her post here.

Fixing an Xbox controller broken by Elden Ring

I have been enjoying Elden Ring on the Xbox but not so much when my controller broke. I recall the same thing happening with Dark Souls. Maybe it’s the way I play, but the problem is that the right bumper is used for a quick attack, which I use constantly. The bumpers seem to be less robust than the triggers, so after a while it breaks.

Fortunately the current Xbox controllers (I have a Carbon Black) are easy to fix. The hardest part is getting the textured panels off the controller handles; like so many modern electronics cases, these are a press fit and have to be levered off while trying not to break or scratch them. Then you undo two screws each side using a Torx T8 security screwdriver and another screw under the label in the battery compartment. Then you can carefully remove first a central rear panel and next the rear bumpers.

This revealed the problem: a small plastic tab had broken.

Gluing the tab back probably would not last long; but fortunately compatible bumper parts are available for a few pounds on eBay. I bought two (one for next time) and everything is fine.

The two key things I do with a new Mac

My Windows laptop is ancient (2015) and my company decided to replace it with a MacBook Pro especially since we need to develop software compatible with Apple Silicon. The new Mac works well  and I have been busy putting the essentials (for me) on it: Xcode, Visual Studio Code, .NET 6.0 SDK, Microsoft Office and so on.

Tip for .NET developers: when you put .NET and VS Code on an M1 Mac, you might get a CPU not supported error from Mono, at one time a dependency of the OmniSharp language server. You can fix this either by installing rosetta 2, the x86 translator for Apple silicon, or by setting omnisharp.useModernNet – see here for details.

There are two things I always have to do with a new Mac. The first is to go to  System preferences – Trackpad  – Scroll & Zoom and uncheck the mischievously worded option Scroll direction: Natural. This seems to set this for the mouse too. The reason is that as far as I can tell the Apple preference is no more or less natural than the older approach and having it different depending which operating system you are using is confusing. My suspicion is that Apple introduced this in order to make it harder to switch between Mac and Windows.

image

The second thing is a bit trickier which is to install my password manager. I use Password Safe which does not offer an up to date Mac download, nor an Apple Silicon version. There is a commercial version in the App Store, but since it is open source my solution is to build from source. I recall doing some tweaking the last time I did this, a couple of years back for an Intel Mac, but the process seems to be smooth now as a few fixes have been added for Xcode and arm64 support. I used the latest development release of wxWidgets, 3.1.6, which has to be built first. My build declares itself to be v 0.01 OSX.

image

Without the password manager a laptop is almost unusable for me since I don’t know many of the passwords I use and generally prefer not to save them in the  browser.

My desktop PC which I use for the majority of my work remains Windows and I am a fan of WSL (Windows Subsystem for Linux) which from my perspective is the best new feature of Windows since the release of Windows  7. I miss WSL on the Mac though it is less necessary because macOS is a Unix-like operating system.

In general I do not have a strong preference between Mac and Windows, though I feel that Microsoft and its OEM partners have some work to do to get Windows on Arm working as well as M1 Macs. I was also disappointed by Windows 11, particularly by its lack of support for slightly older CPUs, and the new Start menu and taskbar which is a step backwards from Windows 10. The appearance of ads in the user interface is a concern too, though it is minimal if carefully configured.

Microsoft moves towards UDP in place of TCP for Azure Virtual Desktop, claims lower latency and higher reliability

Microsoft has announced the public preview of Azure Virtual Desktop RDP Shortpath for public networks – a bit of a mouthful, but what this really means is a switch towards UDP as the first choice transport for remote desktop sessions on the Azure cloud.

“Long running TCP sessions are problematic” said Senior Program Manager Denis Gundarev. “UDP is more tolerant to the temporary network interruptions caused by wireless interference or by changes in dynamic routing.”

UDP in itself is not enough; for example, UDP “does not care about each individual packet’s packet order or delivery. It does not have built-in congestion or rate control,” explains Gundarev. The implementation for RDP (Remote Desktop Protocol) uses a thing called URCP (Universal Rate Control Protocol) which Microsoft developed back in 2013, for real-time communications.

AVD already supported UDP for private networks, but many users do not have a private connection to Azure like ExpressRoute, hence the introduction of the public network version. Microsoft says that the benefits include lower latency, better network utilization, and high tolerance to packet loss.

Implementing the preview is done by setting a registry key on the AVD session host, so this can be done experimentally for just a few hosts in order to try out the feature. That said, it will not always be possible. “RDP Shortpath may fail if you use double NAT setups,” said Gundarev. Users should not notice as the old TCP-based connection will be used automatically instead.

Thoughtworks: do not choose to develop Single Page Applications by default

I have a lot of time for Thoughtworks, a global software development company, and always look at its Technology Radar, the latest version of which appeared recently. Plenty to digest, but what caught my eye was this comment regarding SPAs (Single Page Applications):

The sheer prevalence of teams choosing a single-page application (SPA) by default when they need a website has us concerned that people aren’t even recognizing SPAs as an architectural style to begin with, instead immediately jumping into framework selection. SPAs incur complexity that simply doesn’t exist with traditional server-based websites: search engine optimization, browser history management, web analytics, first page load time, etc. That complexity is often warranted for user experience reasons, and tooling continues to evolve to make those concerns easier to address (although the churn in the React community around state management hints at how hard it can be to get a generally applicable solution). Too often, though, we don’t see teams making that tradeoff analysis, blindly accepting the complexity of SPAs by default even when the business needs don’t justify it.

This struck a chord with me because of my adventures creating an online bridge playing platform using ASP.NET Core. I picked the platform because I was in a hurry, like C#, and had some existing code for implementing a bridge game, done for Windows. Any online game though needs lots of JavaScript and I soon became aware that the traditional ASP.NET approach, where each web page is a separate .cshtml file with server-side rendering and C# code-behind, is at odds with trends towards SPAs and JAMstack (JavaScript, API and Markup, where “Markup” is HTML and CSS).

Note that you can of course do SPAs and JAMstack with ASP.NET; ASP.NET is a nice technology for implementing an API and there are Visual Studio templates for things including “ASP.NET Core with React.js and Redux”. A Razor Pages application is still the default though, and gives you a UI for the ASP.NET Core Identity for free which saved me a lot of gruntwork. Still, as I got deeper into JavaScript libraries, including the AWS JavaScript SDK which I am using for audio and video, I found myself being steered towards React.js (resisted so far) and JavaScript bundling with Webpack (tried but was not a good fit). I also found that even switching my JavaScript code to TypeScript was surprisingly awkward, considering that the creator of TypeScript works for Microsoft. I found myself wondering if I should have started with an SPA, or convert my application to an SPA, in order to fit in well with the new world.

Separately, I’ve been involved with another project, in PHP and JavaScript, which is an SPA, and hitting some of the potential issues. For example, the application made a ton of database queries on first load, the data from which was in most cases never used, as users did not visit the parts of the application that required them. Refactoring to load this data on demand has made the application faster and more efficient.

A problem, which Thoughtworks alludes to in a remark about “closing the gap on user experience,” is that staying in JavaScript rather than loading a new page from the server generally makes for a smoother application. The way my bridge application has evolved is that the main play screen is a kind of SPA: everything is done in JavaScript and API calls, and I have written a ton of JavaScript code for things like rendering HTML tables where server-side rendering with Razor would be much easier, but unacceptable for usability. However, different parts of the application still use separate Razor pages, for things like viewing results, configuring a user profile, finding a game, and admin screens for managing members and running sessions.

JavaScript, now TypeScript, has exceeded my expectations in terms of performance and capability. It is annoying at times but a modern web browser is a phenomenal platform. I was glad though to see Thoughtworks noting that going the SPA route is not always the right decision