Lets assume, that your company has just developed a game-changing product that will alter the fundamental fabric of the planet. However, a strong wall stands tall in the face of your product's full potential: Documentation for software. Technical documentation in software engineering is an umbrella word that refers to any written papers and resources related to the development of software products. All software development products, whether developed by a small team or a big company, require some level of documentation. This is where Technical Writers become superheroes. Writing is a communication skill that is mostly learnt and mastered by practicing it. Good command of grammar and punctuation may seem to be an important ingredient, but technical writing is so much more than this. These days, technical writers have a formal seat and a voice; they are no longer tucked away behind the engineers.
Technical writers not only need to be careful about the grammar and the formatting of the document but they should also pay close attention as to how they can immerse themselves in the technology, business, and applications of the projects they are tasked to document. Only then, they will be able to convey the actual purpose of the documentation. To do that, technical writers need to consider few strategies that entail getting requirements from the SMEs until the product has been tested.
The great American author Thomas Pynchon started his journey as a technical writer before becoming a renowned and acclaimed novelist. Thomas Pynchon translated complicated information related to rocket operations into user friendly manuals for the military wing of Boeing. And while we all may not be as gifted as Thomas Pynchon, we can always choose to go for few pointers in our mind ab initio composing any documentation.
The most important aspect of documentation is to treat it as a standalone product. Just like SDLC phases carried out in software releases, documentation is also based on phased and iterative approach. So we have to plan, create, deliver, and manage the content just like any other deliverable. For initiating any documentation, we have to have a content strategy for it. Content strategist can either be the author or the Project Manager. They are those brave souls who conduct critical analysis and triaging of content so that the organization of the document is right according to the nature of the client.
At its core, content strategy emphasizes entirely on the reader. We must know our target audience ab initio documenting a certain feature, component, or use-case. We must put ourselves in the shoes of the reader so that we can come up with a content that just what the reader was searching for.
Document tends to bridge the gap between the developer (practitioner) and the user. In this way, it serves the purpose of communication. The best practice for communicating through a document is to follow the 7 C’s of communication. According to the 7 C’s, communication needs to be: clear, concise, concrete, correct, coherent, complete, and courteous.
For writing any kind of document, be it proposal or a user manual, it is important to have close communication with the upper management for the timely feedback. Moreover, it is also crucial to closely communicate with developers to comprehend technicalities and keep them in loop for any iterations or revisions related to that specific document. In general, best practice is to keep your colleagues in loop regarding the progress, and document findings and processes for others to use if it is related to them in one way or the other.
Documentation is an essential component of every contemporary business that strives to be the best. The presence of this critical component indicates the existence of a business process for planning, managing, and tracking software development at all phases of its lifetime. It is engaged in every step of the software development life cycle and therefore appears in a variety of formats, each of which is distinct in its own way.