This class will provide you with many opportunities to practice the art of technical essay writing. Here are some simple guidelines you can use to avoid common problems.
Don’t misspell words. Use appropriate grammar. If you are not confident, avail yourself of online tools to check spelling and grammar prior to publication.
Although many of your essays will be based upon your experiences doing home assignments (i.e. experiences), do not write your essay as it if were a private email to the professor explaining the assignment.
Instead, write it “for the world”. Assume some random technical professional has been googling and your essay came up. Make the essay self-contained, self-explanatory, and useful to that random professional. Minimize the assumptions you make about that person’s software engineering background (much less their background in this class!) Provide links to background material if necessary.
Not only should you write it for a variety of people, you should write it for a variety of times. In other words, try to write your essay such that if someone reads it in a year, it will still provide information of value.
Make sure that code displays properly in your posting. If you are using Wordpress, refer to Posting Source Code for documentation on the [code] shortcode.
“Properly” means that the code looks like code, not like text. For example:
def show
@widget = Widget(params[:id])
respond_to do |format|
format.html # show.html.erb
format.json { render json: @widget }
end
endNote that the [code] shortcode supports a variety of parameters. The two of most interest are the language parameter and the highlight parameter, which allows you to highlight the lines of interest within a larger body of code.
Good essays have some sort of internal structure. Help the reader understand this structure by providing internal headings. These headings should not be H1 (that’s too big). Depending upon the theme, H2 or H3 will look good.
You will occasionally want to quote another writer in your technical essays. This is fine as long as you do not present those words as your own.
If you are just quoting a single sentence or two, you can simply use quotation marks and provide the author’s name. For example:
As noted by Steve Jobs, “Design is not just what it looks like and feels like. Design is how it works.”
For longer quotes, use the <blockquote> environment along with <footer>. For example:
A cynical young person is almost the saddest sight to see, because it means that he or she has gone from knowing nothing to believing nothing.
Just because the essay is technical in nature, it doesn’t have to be boring. Try to inject your personality into your writing. You can have “clever” titles, pop culture references, and so forth.
On the other hand, don’t go overboard on the cleverness. Ask yourself: would I be embarrassed if my mother read this essay? (Because she might.) Would I be embarrassed if a potential employer read this essay? (Because she might.)
The goal is to be creative, to show some personality, and to make the essay fun to read as well as informative.
The quality of your essays will rise substantially if you develop them as follows:
The editing pass will normally catch a lot of problems and allow you to refine your thoughts significantly, as long as you’ve stepped away from the essay for a sufficient amount of time to allow yourself to see it with “fresh eyes”. The best way to do that is to sleep on it overnight, but if you don’t have that much time, then at least do something different for a few hours. This lets your subconscious go to work on the material.
Make sure your post looks nice when retrieved both on a laptop and on a phone.