Welcome to section one lesson one.
Let's get started with an overview of section one. In this section we will be focusing on Technical Descriptions and Specifications. The lessons in this section will present a three step process by which you can plan, partition and organize your technical description.
So let's get started with the first lesson. Descriptions and specifications are important documents required by engineers. Specifications allow us to describe a product in great detail. While a description is used more for sales purposes.
The first step in writing these types of documents is to know your audience. This requires planning and researching.
Just like a good journalist you need to be able to answer who, why, what, when, where and how. When it comes to who will read your description, why is it needed, what will it be used for, when will it be used, where will it be used and how will it be used.
You should also know the purpose of your description. Just like a mission statement describes what an organization will achieve, so does the purpose of your description. Take time in understanding the purpose of your description. Ask yourself what are you trying to explain, clarify or describe.
Another thing to keep in mind is the technical competence of your readers. Descriptions are written for people who are not familiar with the subject. Therefore you will need to adjust the details and complexity of your writing accordingly.
Furthermore understand the context in which your description will be used. Ask yourself will this be printed out and read on physical paper? Or will it be read as a digital document? If so do my readers prefer using a mobile device or their laptops?
When researching for your description, know that you have to rely on your experience. Meaning you will need to interact with whatever you are documenting. For example if you need to describe a new feature, have the developers provide you with a prototype or even a working version of the software. This way you can try out the new feature and document your findings.
Having domain knowledge is also helpful. For example if you are documenting software meant to be used in the banking sector. It would be helpful to research some background information. Such as the workflow involved in onboarding a new account holder. This is where search engines and interviewing a subject matter expert (SME) would come in handy. In most organizations an SME is also known as a business analyst.
So that's it. We have come to the end of this lesson. To summarize we learnt what question you need to ask when planning for your document and how to conduct research for your document. See you in the next lesson.