Writing about code vs. writing code

Published Jul 02, 2017
Writing about code vs. writing code

I once wrote a tutorial about implementing REST in IIS 6. It was a reasonably well received piece, although looking back on it now, probably a little flowery in its language for a piece about writing HTTP Modules, back in the day when that was something you might have to do.

Other than that I've not really written about code.

I think it's because I'm interested by aspects of code that I see as niche or tangential. If I want to know how to do something then I usually can find out. Someone's done that job of technical writing for me. When it comes to the actual coding how to code is often taken care of for many technologies that aren't brand new.

Brand new tech, of course, there is a problem with getting a good overview when the world of development isn't familiar enough with the new thing to have generated umpteen Stack Overflow questions about all the major gotchas. The problem with new tech is that it is rare that I am on the cutting edge to write about it.

Recently I did some development using ASP.Net Core, and that is definitely new enough that there's still not a wealth of answers to questions regarding it. It also didn't help that when I began the project in November the latest version, which was, I believe, the second major release, was still quite new and also very different to the first release.

I don't think I'm giving .Net Core its due for how complicated it has been to work with. If you have worked with it you will know that it is a pretty radical change in thinking from the previous structures, using things like json files and tight integration with nuget and bower to achieve just about everything. A web tech that uses IIS as a pass-through to an instance of its own server that runs on a per application instance is pretty different all round.

Those two paragraphs do very little to describe all my experiences thus far with Core. Therein lies another problem. If I wade into something like that I generate enough material for a book very quickly, but does anyone want to read my book about .Net Core? Maybe, but I don't think writing a seat-of-the-pants journal of my experiences with a new tech are really the place to start.

If you're going to try something new surely it would be better to start where you're comfortable. Where is that?

That's something I'm really not comfortable thinking about. Where I'm comfortable in my development. A lot of places where I could be of value to people who know way less than me are catered to already. Places that aren't catered to often don't have broad appeal. Places that aren't catered to where a clear need exists are the places where I think most developers feel uncomfortable.

These are places like making a development workflow that is better than "Start", "Write Code", "Finish" but isn't as fussy as Agile wants us to be, and doesn't involve scrums where there is no team, or unnecessary pairing, or pointless code review that has no set agenda.

I believe that most developers know how to solve a programming problem, but a workflow problem? People appear to stay well away from those.

Of course the other place that I can bring something back is to discuss problems discovered in code that result from, probably, not having an ideal workflow for development. I understand that the customer can be awkward but they always are, so really, when you come across some truly atrocious code you have to look hard at your own organisational skills.

When you realise that what you ought to be writing about is not the code but the developer that's when you get really uncomfortable. So I guess that's where we should be. Uncomfortable and thinking not about how we're going to write code but about how we're going to write code that is a bit better than the code we've seen in legacy projects.

Discover and read more posts from Leo Stableford (Eno M Koney)
get started