What I Want To See In A Writing Sample

Submitted by Morbus Iff on Wed, 2003-01-08 19:51

A friend recently applied for a job where the employer asked for a sample of your business writing or a sample of previous work that demonstrates your organization, analysis, and logical thinking skills. An example of this type of documentation would be; system analysis documentation, business modeling, process improvements, etc.. He asked me if I had any candid thoughts on what I'd want to see if I was said employer. I'd grade him highly on the following:

  • not reinventing the wheel unless absolutely necessary. if you do need to reinvent the wheel, I want to know why. it'd annoyed me to see "wrote a CMS doing this, this, and that", when I could just say "well, why didn't you use this, that, or this? they all do that."
  • bullets. outlines are god. bullets let me know that you can take a central idea and simplify it to a single paragraph. it makes reading easier, discussion easier, and leaves plenty of white space for pen scribbling revisions, questions, or additional thoughts.
  • sections. think the <h1>, <h2>, <h3> tags in HTML. knowing that you can compartmentalize a process into chunkable bits. this is similar to bullets (but is less points than a tree).
  • how to revert your changes. if I'm going to be following your instructions, I want to make sure that I can follow them backwards to undo any mistakes. likewise, if a change can NOT easily be reverted in a few simple commands (and this is some sort of new feature, server changeover, complicated revision cleaning, etc.), I want to see that you've prepared for the inevitable disaster. whenever I write process lists or new feature explanations, I always have a "if this goes horribly wrong, enter this one command to revert". this one command could do hundreds of different things - as long as it was all encapsulated.
  • answering unasked questions. prepare me for what I'm going to ask next. if something is going to happen that could raise warning flags ("[err] snizzipt is not installed!"), let me know with a "you may get an error about snizzipt. don't worry about it. or, perform the following...". this lets me know that a) you've run through the process before, b) you know all the various roads less travelled, and how to deal with them, c) you're preparing for things you didn't expect (as with "revert your changes", above).
  • reason. if a decision has to be made that's not clearcut, tell me why you chose what you did. I want to know pros and cons, with a special gleam on the future ("whilst we may not need this in the future, it takes very little to enact, and the extra features give us a lot more power if we need them").
  • tell me how you solve a problem. tell me how you code. what do you do first? what step do you actually start coding (it's step four or five on my list). what books have you read that have inspired your coding? why do you design databases this way? what have you learnt in the past that make you better than everyone else? how do you document code? do you use a CVS server? how do you handle annoying customer requests after you've begun coding? and so on, and so forth.

Anyone got anything else I could suggest to him (or my readers)? The most recent thing I've written that follows a decent amount of these maxims was my first Apple article on installing Perl 5.8.