Tool independent Technical Documentation

-

    My cost-saving ideas apply to the following: lessen recurring costs incurred on maintaining technical documentation & decrease the technical supports costs by making technical support information easy to access

The idea involves setting up a documentation system that involves Markdown and Static File Generator. Both cost almost nothing and are highly reliable and secure. Consider that you want to digitalize an entire library of books. We need to consider tools for this so that the file format will remain valid even after a hundred years. We need easy to catalog documentation archival, built incrementally and available online from the start. I suggest using Wiki format (such as Media Wiki), Markdown, or LaTeX. My preference is for Markdown format as it is easy, and the files can be online or offline. The same thing applies to Technical Documentation for a product company. We need to have technical documents for the long term, and we must try to avoid tools dependency and use a common standard such as Markdown. I am into Technical Writing, and we generally use tools and frameworks such as DITA, MadCap Flare, and FrameMaker, and all these tools are inadequate at some point. Companies invest in converting files from one format to another format. The files in Markdown format will not need converting to other file formats again as this is a universal standard that works with any Markdown editor. In this, every file is a deliverable by itself. I used a Markdown editor called Typora for some of my deliverables. Its minimalist approach makes it very simple and easy to use. It is also easy to maintain in the future.

Please note that product companies spend a lot of money on documentation, and some of the recurring costs are avoidable. It may sound like an exaggeration, but an average of 20 percent of R&D expenses go into creating and maintaining documentation. Even 10 percent saving from it is a notable saving. Also, documentation is akin to lifeblood, and we realize this only when it is missing. We need to increase the certainty of access to information through our documents.

Title image source - https://medium.com/@andrey.dobra/technical-writing-part-3-basic-tools-of-the-trade-66dc9c1b90cf

Related articles:

The ability to learn is the key to survival. We can learn faster by learning from each other.

Comments

Post a Comment

Popular posts from this blog

Insert images in Typora

-
Image
     I started toying with the idea of using Markdown for documentation only a couple of months ago and happened to pick Typora as my choice of Markdown Editor. You can tutor this tool by yourself in a single day, but it takes time to learn some nuances if you are learning it all by yourself. For a long time, I thought Typora doesn't have the option to add a cover page, header, footer, and page numbers, and last week I figured out that we can do all these by using the YAMAL front matter. You can add typora-root-url to the YAMAL front matter to insert images by their relative path. To know more, see: https://support.typora.io/YAML/ https://support.typora.io/Images/ Related articles: YAMAL front matter in Typora Use markdown for your README Why I am gung-ho about Typora Conditional text in markdown Author documents using markdown Using mermaid in markdown Do agile technical documentation using markdown Tool independent technical documentation Techniques for cost-effective ...
Read more

Apply Goldilocks principle

-
Image
     There is one thing universal about successful managers. They keep increasing the performance benchmark every time. It applies to an athletic coach who wants to make his trainee globally competitive. I have worked under cruelly kind managers who are very ruthless in getting the tasks done. They push you to improve your competency and skills every day. You may have had a tough time working under this manager, and still, it is not something to be resented. Weathers the pressures work? We start looking for ways to do things better when the competitive edge is so narrow, and even a marginal improvement in something will give you an edge over your competitors. I had my dilemmas over if harsh managers are good or bad. A good manager sets difficult but attainable benchmarks and allows members to execute tasks with relative autonomy. There is no use flogging a dead horse. Spend time grooming the people who are motivated to do their best. I have spent time with people who do n...
Read more

Technical Writing essentials

-
Image
     I want to share some of my learnings starting from the beginning days of my Technical Writing career. Everyone in the project must have a cursory understanding of the following, and the Technical Writer must understand it in detail: Language standards Learn the style guides. MSTP (Microsoft Manual of Style - currently called Microsoft Style Guide) is among the most widely followed style guides. You can access it online for free and even download the PDF for offline reference. See https://docs.microsoft.com/en-us/style-guide/welcome/ There are several other style guides, but it is mostly enough to refer only to Microsoft Style Guide. The following are some of the key takeaways: Avoid passive voice - sentences in passive voice are generally longer and harder to read. Use only the simple and easy words understood by the global audience with varying degrees of English knowledge. Your writing must have the same meaning for all people from different geographies and culture...
Read more