Technical Authoring

Did I write the ARM ARM?

(For those not in the know: the ARM ARM is the ARM Architecture Reference Manual.)

Well – yes and no. The 3rd edition, ARM DDI 0406A, published in 2007, that is. I spent two of my nine years at ARM doing little else. For the first of those two years, I was the only author on the project; for the second year, I shared the job with GH. But do technical authors write the books they author anyway? That varies a lot.

The information comes from the engineers, often in the form of a document that the engineers think would be good enough without any attention from technical authors at all, sometimes as incredibly scrappy notes, sometimes as spoken words in a series of interviews. Sometimes the engineers’ documents really are pretty good, but often they’re difficult to follow or have gaps, and sometimes they contain actual errors and inconsistencies. As you write the book, you often have to seek clarification from engineers, or get them to check a section to make sure you’ve understood something.

When you’ve finished writing a book, the engineers have to check it for technical accuracy, you edit their corrections into the book, and they check it again. This process can sometimes be quite a long series of iterations.

All this is complicated by the fact that what you’re writing about is generally changing as you’re writing it, because the engineers are working on the project, and they often find the design has to change, either because of unforeseen complications that only become apparent as the project progresses or because the end user requirement changes. And of course the book has to be ready to deliver at the same time as the product it describes!

The Assembler Guide

I can fairly say I wrote the Assembler Guide. The original version was my concept, I selected the material to go into it, and I designed the structure of it. I borrowed quite a lot of the words from the ARM ARM as it then was and a few words from elsewhere, but I chose which words to borrow on a sentence by sentence basis or on an even finer granularity than that, rewrote an awful lot of them, and wrote an awful lot more myself. Of course I didn’t write the Assembler, and the content of the Assembler Guide has to describe the Assembler. But I do program in ARM Assembly Language myself, and the Assembler Guide is for programmers.

After that, as the Assembler developed further, other authors took over the Assembler Guide and it grew with the addition of a lot more material – but the basic structure remained as I had designed it, and most of the additional material followed my structure. Then, in a terrible rush because I was really very busy on the ARM ARM, I shoved all the Neon and Thumb-2 material into the Assembler Guide, because I was the only author who really understood it all at that time. A bit of a mess, I’m afraid, but at least it all got in there, and was almost entirely correct if a little confusingly presented. Later, I got a chance to tidy it up a bit, but not completely.

The ARM ARM

I didn’t design the structure of the ARM ARM, or select the material to go into it – that was done by a committee consisting of DS, RG, DB, MW and me. GH joined the committee later, but by then the main structure was designed. I’d say RG did the bulk of this work. That’s at the top level – the division into three parts, and how the instruction set description is divided between Part A and Part B. The structure within Part A is DS’s and my work, and the structure in Part C is largely MW’s work. Part B is DS’s, RG’s and my work – DS and me on System Instructions, and RG on Memory Systems. That’s the structure and content selection.

The instruction description section in Part A – much the largest part – was actually implemented in a very co-operative fashion between me and DS. I laid out instruction pages and inserted the information into them, and then we discussed them and I tried to implement what we’d discussed, all in a very iterative way until we were satisfied. Once we’d got the instruction page design worked out, I inserted all the information into all the pages. In the course of this process, a few problems with the design emerged, so we adjusted it and I adjusted all the pages to the modified design – again, a somewhat iterative process.

The System Instructions section of Part B followed exactly the same page design and process.

I wrote the instruction group tables that cross-refer into the instruction pages – they form the next biggest section of Part A.

I pulled the rest of the Part A together. Some of it I wrote myself, some of it was written by DS and edited by me, and some was written by DB.

Apart from the System Instructions section, GH took over most of Part B and all of Part C halfway through the project. MW had written a pretty good engineer’s document for Part C, which I had got into tech pubs shape, by then – but an awful lot changed or was added during GH’s time. RG was writing his engineer’s document for Part B (apart from System Instructions) during the first year, so getting that into tech pubs shape was mostly GH’s baby.

So all in all, I did about two thirds of the authoring work on that issue of the ARM ARM – but the involvement of engineers was a good deal more than in many projects.

Before that, I’d written first the Thumb-2 Supplement and then the Neon Supplement for the earlier ARM ARM – and those were much more my own work, working from very cryptic (but precise and accurate!) engineering documents written by VV and SF respectively.

I even wrote the pseudocode in the Neon Supplement. It was checked by SF, who made a few corrections. This was a significant input into a complete redesign of the pseudocode for the ARM ARM – DS ripped it to shreds, then went back and looked at the pseudocode in the earlier ARM ARM and realized it had always been just as bad, or worse, throughout. DS wrote all the pseudocode for the new ARM ARM, making it all beautifully consistent – a real labour of love. My only input into it was suggesting a few macros to help shoehorn some of the instructions into their pair of facing pages!

Of course both the Assembler Guide and the ARM ARM have changed a lot in the years since I retired!
Insiders will recognize some or all of the initials. I don’t think I’ve said anything inaccurate or inappropriate – if I have, please let me know and I’ll fix it!