Sooner or later, in business, even in IT, almost everyone must write something more than simple emails. Procedures, standards, business cases, proposals, plans: All kinds of things may need to be authored by everyone and contain descriptive narrative about the subject at hand. Much documentation can be found on the internet, but your organization’s internal rules, goals, and desires cannot be found via a Google search. Even database designers and data architects must contribute to corporate internal literature.
It is not unusual for writing tasks to be avoided or addressed with eyes closed, dashing off something and hoping whoever wants it will simply accept whatever is provided without question. As Hemingway was once quoted, “There is nothing to writing. All you do is sit down at a typewriter and bleed.” Admittedly, the typewriters are relegated to attics and museums, but people often fear the potential flowing blood when the need is to write something much, much longer than a tweet. Failure to be trustworthy in longer narrative forms can be career-limiting. Many job descriptions include the requirement “able to communicate well in both verbal and written form,” and some of those jobs even mean it. For those who fear writing documents, whether standards, proposals, or anything else, there is hope. It helps if one can calm down the terror filling the brain when starting a document and then proceed to simply focusing on the purpose of the document. Who is the target audience? Business users? Peers? Support staff? What information is needed by the target audience? This desired information is the content to be communicated.
Having templates or sample copies of similar documents helps provide a little starting structure. An initial pass at creating simple section headings can serve as an outline to help organize thoughts. From there, one can jump around and across any of the sections to start filling in the knowledge to be transferred.
Once most of the basic ideas are drafted, then one can work through the document and clean up the text. At this point, one worries about thoughts sounding coherent and details flowing smoothly from section to section. Is what is written clear and not open to misinterpretation? The author should try to imagine being in the audience’s shoes: Has enough of the right information been written down? If you, as the author, do not understand your document, how is any other reader to understand it?
Rework your content until you feel comfortable with the results. While you are in the draft stage, you are free to move things around any way you wish if you believe it improves your message. Have a peer review your document to give you feedback. I often end up writing any introductory section after everything else is done.
Writing documentation may be considered painful, and one may think it sucks, but it does serve a useful purpose. Obviously, unnecessary documentation should be stopped in its tracks. If there is no audience, it does not need to exist. Communication is hard: Producing clear, concise, and accurate communication is even harder. The better one’s finished output is, the better for everyone.
While AI has helped enhance our world, and some kinds of documentation can be auto-generated from code, the ability to describe the business, examine reasons for or against an idea, and detail future plans suggests why people still need to have written documents. Maybe in the not-too-distant future, we will have organizational-level equivalents of Tik-Toks, YouTube videos, and podcasts laying out all our practices, standards, and business cases. And then instead of the fear of writing, we will need to deal with the fear of being recorded. Until then, we still need to write.