Writing
Despite being developers, we don’t exclusively write code. There are times when we find the need to write other kinds of materials; like blog posts, technical documentation, training materials, and detailed outage reports. What follows are some recommendations and best practices when it comes to writing.
Blog
Many organizations have blogs on their sites with content written by employees. There are also many developers who have very successful personal blogs discussing any number of technical topics. Below are some general guidelines you should follow when you are putting together a blog as a whole, and writing individual posts for it.
First and foremost, DO NOT PLAGIARIZE! Nothing will discredit your blog quicker than stealing content from somewhere else. With that in mind, researching your topic, quoting references,and citing your sources are not only accepted, but encouraged!
The content of your post should be wholly unique, but you don’t have to be the first person to write about a specific topic. Tons of people have written about tips and tricks on SEO, but that doesn’t mean you shouldn’t.
Speaking of SEO, you should definitely take that into consideration when putting your blog together, as well as for each article that is posted to it. Your post should include the proper metadata, a headline containing an attractive and attention grabbing title, as well as optimized keywords. Here is a great checklist for optimizing your blog post.
Before you actually start writing anything, be sure to determine the intended audience for not only your blog as a whole, but for each individual post that is authored for it. This will keep your posts focused, topicical, and also helps to engage readers.
When it comes to the actual writing part, there are some fairly obvious writing techniques that you should follow that will improve the quality of your blog. First, be sure to use proper spelling, punctuation, and grammer. This seems obvious, but there are far too many blogs out there that have yet to hear of spell check. Also, don’t write in a vacuum. Have others proofread your post prior to publishing in order to improve the overall quality of the post.
You should also be concise. Writing a massive post, filled with tons of personal anecdotes and tangents will kill your blog. If you have a ton to say, you should break it up into smaller chunks within the post, and even make it become multiple blog posts instead of one giant post.
If your goal is to grow a healthy readership, posts should be published on a regular schedule. This is challenging for many individuals, but is necessary. One way to get around this is to write several posts prior to actually launching your blog, so there is always a buffer of upcoming posts. For organizations building a corporate blog, multiple authors within the organization can be assigned writing tasks in order to produce content on a regular schedule.
Technical Material
Developers are often tasked with creating various forms of technical documentation or user guides, and often this technical material is handed over to clients and end users of the software, so it is important that the materials provided are as well crafted as the code.
Before you begin writing anything, you should determine who your audience is going to be. The documentation you create should be relatable to the intended audience. For example, creating a guide for developers to interact with an API is going to be very different from a guide for non-technical users who need to create a new user account in an application you’ve created.
You should also write from the perspective of someone who has never used your software before. Take into consideration their anticipated level of technical ability, and their familiarity with using software similar to yours. Coming from that perspective, you’ll be better able to recognize the areas where you will need to provide more detailed information.
Another thing to take into account are the use of screenshots. Pictures are worth a thousand words, but if those pictures become out of date (e.g. when an update heavily changes the styles and layout of a website), the client will definitely have words for you, and none of them will be good.
You should also avoid writing in a vacuum. Have others review your work, much like how you would have someone perform a code review on any code you’ve written. You may also find that many different writers are writing documentation that needs to be merged into one large document. When that is the case, a good idea is to have one person bring these different documents together and focus on ensuring that the tone and writing styles all mesh well together, so it appears that it was written by a single author.
Code Comments and Docs Generation
While we are discussing technical documentation, we should definitely bring up the creation of documentation from the code itself. Many modern languages have “Docs” style commenting systems which allow you to generate documentation from classes, methods/functions, etc.
Code should be self documenting, but the creation of these kinds of comments really will help future developers who work with your code, even if you never export the docs from the code.
It is crucial to be accurate on documentation. Misleading comments can through off developers, costing hours of work.