Language Documentation and Compilers

A few years ago, I had the great pleasure of working on a compiler for a proprietary programming language. The first thing I had to do was document the language, because it consisted mostly of a set of LISP functions that acted as an interpreter, whereas I had to create a high performance compiler for a more traditional runtime environment. It was a beautiful language but a bit complicated with many variations on argument types, specifically lists, “atoms” (the LISP word for keywords, sort of) and other functions. I wrote a detailed syntactical and semantic specification, and then pretty much converted that into a series of functions in a more conventional programming language. It was also necessary, because of the limitations of my development environment, to think of the parsing and processing of the language as purely linear rather than being loadable into an entire expression in a memory tree and parse it from there.

The good thing is that it actually worked, and I was able to build a very fast compiler for this beautiful programming language; but had I not documented it first, it would have been very, very difficult to build an efficient compiler in that very un-LISP-like programming environment. So it was quite an exciting project and, in my own opinion, very successful, and a real pleasure to both document and build a compiler for this lovely language. Yet another reason why I enjoy technical writing so much! Please feel free to write with any questions or post comments. I keep track of them!

Thanks for reading,
Andy Schaub

Artisan Writing

So what do I mean by artisan writing? I mean the ability to craft words into explaining complex technical concepts in simple, ordinary language that allows anyone from a programmer to an end user to understand what they are reading and to “get it” conceptually. I know that one of the most rewarding technical writing experiences I have ever had was writing documentation for a program I was implementing based on a specific and proprietary algorithm. Someone else needed to re-implement the program in another language and he did so without even looking at my code, just reading the documentation including some diagrams describing the different phases of the algorithm. It worked perfectly and I was delighted. I have had similar experiences writing end user documentation.  I’m going to keep this week’s post a little short because I’m a bit ill but be sure to come back next week for more about technical documentation and artisan writing!

–Andy

Technical Writing / Software Development

So what do I mean by technical writing and software development, since there is obviously a connection if you’re documenting software? Well, think of it as architecture. Most architects are both scientists and artists in that they understand the physics of building materials and construction techniques as well as needing to express themselves aesthetically within the context of their client’s needs and desires. So, in a sense, technical writing is like architecture in that the writer must have the ability to understand technology – possibly by being or having been a programmer or engineer him or herself – but also be a wordsmith who can carefully craft language and often create illustrations that describe and demonstrate the technology to an audience ranging anywhere from other programmers who need to implement programming languages or binary compression algorithms to end users who simply need to know how to make their iPhones work.

There are many technical writers out there who really have no background in technology but have the ability to intuit, either naturally or by experience, how things work and to describe them clearly. I, personally, am in the set of people who have backgrounds in technology, having implemented graphical user interfaces, programming language parsers and binary compressions algorithms, whom happen to be, at the same time, English majors from places like Stanford where I took my original computer science courses. So I really do have – and I think there is a need for this without meaning to disparage all of the many fine technical writers who have no formal background in technology – the equivalent of a kind of degree in “technical writing architecture”, having carefully documented and specified virtually every program I have written since beginning my career as a software engineer.  To that end, I would really like the opportunity to work with you and will be making regular posts on this general subject without (always) hawking my own services.

Thanks for reading!