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.
The techfolio template essay files are named with the date they were created (i.e 2015-08-26.md). Don’t do this: name each essay file to reflect its subject matter. For example, you might base the file name on the title of your essay. If your essay title is “Igniting the fire”, then your file name might be “igniting-the-fire.md”.
Do not include spaces in the file name: use “igniting-the-fire.md”, not “igniting the fire.md”.
This is important so that the URL associated with your essay provides some indication of what the essay is about, not just the date on which it was created.
Do not name your essay with the module name (i.e. “Configuration Management”) or the experience name (i.e. “Reflections on Javascript”). Would you want to read an essay based on a title like that? I sure wouldn’t. With a little bit of thought, you can come up with something personal (i.e. “The configuration management catastrophe that almost cost me my job”) or clever (“You can’t always git what you want”).
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. Don’t create sections to answer each of the “questions” from the prompt. If you do that, you’ll almost certainly create a boring essay that is not interesting to read.
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 useful.
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. If you’re a newbie to the subject, then write it to provide insight and understanding to other newbies.
To make an essay compelling, it is usually helpful to “tell a story”. Create a narrative, don’t just answer questions.
Make sure that code displays properly in your posting. You accomplish this by using fenced code blocks and syntax highlighting. Here’s an example of javascript code highlighting :
function getTotalCost() {
let cost = 0;
for (let drink of this.drinks) {
cost += drink.price;
}
return cost;
}
Think carefully before including large code snippets (beyond, say 50 lines). As a rule of thumb, keep code snippets to a reasonable length and make sure all of the code is directly related to the subject of your essay.
Good essays have some sort of internal structure. Help the reader understand this structure by providing internal headings. Don’t start with H1 (i.e. # in Markdown), as that’s reserved for the title of your post. Instead, start with H2 (## in markdown), then create subsections within that section with H3 (### in markdown), etc.
Similarly, use itemized or enumerated lists, tables, etc as appropriate.
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 italics, 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.
As they say, “A picture is worth a thousand words.” It is very easy to include pictures and videos in your essays. If the meaning of your essay will be communicated more clearly with images, take the time to find and include them. See the Formatting section of the TechFolio User Guide for instructions on how to include images and video.
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.
Once you’ve written and published it, retrieve it in a browser and see how it looks.