Maruthi Prasanna

     Passive voice is the slouch in writing. A sentence in passive voice is usually wordier. Passive voice is not encouraged in Technical Writing. The 'by zombies' method is the easiest method for determining passive voice in a sentence. Add 'by zombies' to a sentence and see how it sounds. The sentence is in passive voice if it is grammatically correct after 'by zombies' is added to it. See the following video: https://www.youtube.com/watch?v=jWTaxXdLj_k Related articles: Technical Writing Essentials The ability to learn is the key to survival. We can learn faster by learning from each other.

     Most of the major product development companies around the world are following Agile methodology now. Agile essentially blurs the line between different roles. We need no clear differentiation between a developer and a tester. But it does not seem so when it comes to Technical Documentation, as the nature of work is quite different. The Agile Methodology helps reduce redundant and duplicate work and shrinks the time it takes to get to the market. The tools we use and the process we follow can help us in our Agile approach. Jot down a product feature under development in Markdown and use it everywhere; in the JIRA, Confluence, and also while making a release. Integrate the README, Release Notes, New Features document, and so on with Markdown, and integrate it with the release build. The Markdown file has .MD file extension. The same file is both reader and writer. It is both the working file and the final output file, and it is not required to convert the file to any other output

     You can use the Quick Parts feature in Word to apply reusable content. I am using this method to create a Release Notes template. You can insert this Quick Part in a blank document, and the Release Notes document is ready once you fill in the content. Add the following demo content into a blank Word document: Now, do Ctrl+A and select Insert > Quick Parts > AutoText > Save selection to AutoText Gallery . The following window is displayed. Change the name to RN template and click OK . Now, you just need to open a blank Word document and select RN template from the Quick Parts whenever you need a template for creating release notes. The ready to use Release Notes template will look as follows: If you are into Technical Writing for a decade and a half or longer, you will surely remember the times when MS Word was the first choice for creating all sorts of documents, but it gradually changed. I believe the time has come to look at MS Word favorably once again. The DOCX i

     It is easy to implement content reusability in MS Word. Select the text and add it to the AutoText Gallery in Quick Parts to make it reusable content. The following image illustrates the same: The following pop-up is displayed: I suggest saving to Normal.dotm than Building Blocks.dotx as it enables auto-completion. The Options setting helps to apply the content as a separate paragraph or page. The changes are saved to the template when you close the document after making all the changes. Enter a minimum of four characters from the Building Block and click Enter to insert content at the current location. Alternatively, insert from Quick Parts to insert at any specific location. Click Organize and Delete to edit the properties or to delete the Building Block. Related articles: Try this release notes quick part Quick formatting guide for Microsoft word I am a fan of MS word Author documents using Confluence Tool independent technical documentation Techniques for cost-effective t

     Every item in the engineering domain has a part number, and this applies to documents. Being a Technical Writer, I never worried about the document part number while working for the pure software domain, though it may be desirable to have a part number. Part numbers become essential in an industry in which both software and hard are converging. The part number needs to conform to some standard for it to be meaningful. We can use an SKU (Stock Keeping Unit) Number Generator to generate part numbers. Use one of the inventory applications or create an Excel template for generating SKU numbers. The following are some of the popular SKU Generators: https://www.zoho.com/in/inventory/sku-generator/ https://www.tradegecko.com/free-tools/sku-generator https://www.gorgias.com/tools/sku-generator https://www.primaseller.com/tools/sku-generator For the Excel template for SKU numbers see: https://www.logiwa.com/blog/manage-inventory-with-sku The following link helps you learn more about SKU nu

     Try one of the following sites for royalty-free images when need to embed an image into a simulator or a graphic: https://www.pexels.com/ https://unsplash.com/ https://depositphotos.com/ https://pixabay.com/ Random name generator: https://www.behindthename.com/random/ https://namelix.com/ https://www.classtools.net/random-name-picker/ https://wheelofnames.com/ Try one of the following when you need a custom logo or stylish fonts: https://www.fontgeneratorguru.com/ https://www.fontspace.com/font-generator https://lingojam.com/FancyTextGenerator https://lingojam.com/ https://coolsymbol.com/cool-fancy-text-generator.html https://coolsymbol.com/ https://metatags.io/font-generator Go look for fonts: https://www.fonts.com/ https://fonts.google.com/ https://www.fontsquirrel.com/ https://www.fontspace.com/ https://befonts.com/ https://www.dafont.com/ https://www.ffonts.net/ https://www.freescriptfonts.net/ https://fontsarena.com/ https://pinspiry.com/category/free-resources/fonts/ https:/

     There is no way of getting better answers without asking better questions. Consider this fact; most Indian marriages happen to be arranged marriages. The family looks for the alliance, and prospective bride and groom meet, and the decision happens after a brief interaction. There is nothing wrong with this if it works for everyone. But sometimes the bride is asked if she knows how to cook. Sometimes she is asked to demonstrate skills such as singing. All such things represent a repressive relationship with less hope of anything better for any time. We learn some things together when we start a relationship. The first most important thing is to learn something about each other and have a shared vision for everything that matters for all the parties involved. While interviewing someone, your questions will decide if you are looking for an accomplished Fashion Designer or a Tailor who can do a bare enough job. You do not get good candidates as a result of interviewing dozens of peopl

     I read a blog by Melissa Rosen regarding Knowledge Base. https://www.groovehq.com/blog/building-knowledge-base I want to put in perspective my views along with the ideas borrowed from the above blog. Knowledge Base is essentially an easy-to-access self-service portal for customers and internal employees. I was a part of creating a Knowledge Base for the company I worked for, but it is always an evolving science with scope to consider improvements. A company can build the Knowledge Base internally without the help of any third-party application. Please do not consider this an overkill if I suggest implementing it using a Static Site Generator and author text content using a Markdown editor. All that is important is to have the Knowledge Base hosted online. A Knowledge Base has documentation at its core. Oxford dictionary defines documentation as the media—text, images, and video—that explain a product or service, the material that provides official information. You can implement Kn

     The documents published with Markdown tools generally use Google Fonts that have Open Font License . Thanks to Google Fonts, you have an impressive selection of free web-safe fonts. There are over 1000 font families to choose from and are free for use for a commercial product, and there is no limitation on page views. You are not likely to face any cross-platform display issues while using Google Fonts. They work on literally every operating system and device. Also, you can use Google Fonts without installing them. A webpage using Google Fonts is likely to load faster since you do not need to upload the fonts to your server. The quality of typefaces keeps increasing with libre versions of popular typefaces such as Baskerville and Franklin Gothic. There is also a disadvantage associated with Google Fonts gradually becoming industry standard. The typography will look less distinct when you want to use the font to convey your brand. Related articles: SKU generator Build Knowledge Ba

     This post is going to be a tutorial on Typora with almost end-to-end instructions for a beginner. Install Typora and Pandoc as a prerequisite. Refer to my previous posts or figure them out by yourself.  First, I want to answer why Typora and why Markdown. Typora is a Markdown Editor with a WYSIWYG interface, and it makes using Markdown a lot easier. For those skeptical about Markdown, kindly note that great products may not come with a great endorsement. Technical Writing is not a particularly easy job, but everyone can be a Technical Writer to the same extent to which everyone can be an artist. Markdown can help everyone be a Technical Writer, and an easy-to-use Markdown tool such as Typora can make it even easier. Conduct training on Markdown for all product team members and not just Technical Writers. The content created using Markdown can be easily integrated into CMS. People responsible for the product can write about the product and the features they are developing. Quick ti

     I am writing this post to quote from my own experiences the views I expressed in my previous post. Just like smoke or fog affects your visibility, any grudge will affect your thinking. I will not use the words such as hatred or prejudice because I believe no one deserves it. In a workplace, you may have come across someone who tried to block your entry at the time of the interview itself or tried to throw you out soon after you joined the company. Understand that it is just a part of the survival game. Guard and defend yourself but be empathetic to the other persons' point of view. In one of my experiences, someone vehemently opposed my entry into the company, and they still hired me. That, someone, was required to train me on the project and do knowledge transfer after my joining. The gentleman worked for the company for about ten years. He had reached a career plateau and suspected the possibility of being asked to leave. I had to work closely with him to get knowledge trans

     Success does not just depend on your ideas, commitment, and hard work. It has a lot to do with the bonds you have with your family, colleagues, and society in general. We need to avoid conflicts and foster good bonds. The differences will resurface sometime again if avoiding conflicts is a superficial effort. Only genuine empathy, kindness, and willingness to understand the fear and insecurity in others, and sincere efforts to alleviate the concerns of others can help avoid conflicts. I draw my inspiration from Bhagavan Mahavira . Love and forgiveness for everyone was his motto, and he means it not just for human beings but for all living creatures. This universal love and forgiveness do not seek to exclude even the opponents and enemies. It may be too big an idea for a normal human being, but we must respect and accord the benefit of the doubt to others even when we have disagreements with each other. Sometimes I have faced situations in which I felt it is difficult for me to wor

     I want to list some of the basic things that a Technical Writer must know about MS Word. An MS Word document can be in DOC or DOCX format. The DOCX introduced in 2007 is the more advanced format. The X in DOCX stands for XML standard. DOC and DOCX are compatible with each other, and DOCX has more advanced formatting options. You can convert from DOC to DOCX format, but you do not necessarily do it. PDF generated from either will have nearly the same size. For Technical Writers, MS Word is a document source file, or it is an intermediate file format and rarely the final deliverable. Many tools allow exporting to MS Word. Make some additional formatting changes and export to PDF. Now the final deliverable is crafted! Confluence exports in DOC format. A Markdown tool that uses Pandoc will export in DOCX format. The formatting changes to make are nearly identical in both cases. Now let us see when we should export to Word. I usually export to PDF (provided we have the PDF export optio

     Recently I read Drive: The Surprising Truth About What Motivates Us by Daniel Pink on my Amazon Kindle, and I believe this is among the best management books I have read so far.  I want to summarize what I learned from the book. Genuine motivation has the following ingredients: autonomy, mastery, and purpose . Most people have the drive to accomplish more. During the industrial revolution of a century ago, rewards and punishments (carrot and stick) were seen as the only way to motivate people, but this may not be as relevant today. Rewards and punishments can even be counterproductive. Dangling a reward each time will make people more interested in it than the joy of accomplishing a task. A kid motivated with a prize for a drawing may lose interest in drawing after winning the prize, and it works similarly for adults. Companies must not rely on bonuses and awards for motivating employees. Wholistic feedback is more helpful than a reward. Rewards do not have any additional benefit

     To not let oneself be a pushover is one of the biggest concerns while being a Technical Writer. There are very few people of your tribe in the company, and you may be the only Technical Writer when it comes to your project. People around do not have much understanding of the work you do. You are not as experienced with the product compared with most other people on the team. Technical Writer is not required to stick to a single product or domain. And these are the reasons that can make you a pushover too. Sometimes you may encounter negative attitudes of the people who think Technical Writing is easy. We have the responsibility to assert the importance of Technical Writing. Convince people that you have a keen interest in the product and the domain. It is impossible to pretend this, and you need a keen interest in the product for others to see it. Your ability to understand people and the products is more important than the writing itself. You have to be the go-to guy if you inten

     I believe two ideas help document design and also the product design. Minimalism Information Mapping I want to emphasize the importance of minimalism. Most commercial products suffer from feature creep, with many features added more for novelty than for their use. According to a general estimate, we rarely use 80 percent of product features, making the product UI cluttered and the application bulky. The very same features intended to make the product easier to use will keep increasing its complexity. The same thing applies to the technical writing tools and also for Technical Writing. The writing is highly effective when the idea or concept is both concise and detailed enough.  Most technical writing tools are affected by feature creep. One of the most common examples I want to site is the experience of copy-pasting content from some other source. You are required to clear the text formatting before pasting or while pasting, increasing the number of steps you are required to perfo

     We need a video storyboard, Adobe Captivate or Camtasia software, and a graphic designer trained in using this software for creating video tutorials. But I want to suggest an easier way to create video tutorials. It takes a significantly higher effort to create a video tutorial than create a document with the same information. Videos will have much bigger file sizes and are harder to deliver to the customers. Videos will go outdated very soon when some of the UI and product features change, and it is much harder to edit and maintain videos than maintain manuals. Overall, videos are not economical, and it took weeks-long efforts to create even a small video. It is not surprising that creating video tutorials was a hot idea even 20 years ago, but it never really took off. Now come to probably the easiest way to create a video. Create a YouTube channel for your company or the product. A lot of big and small companies already do that. Create a neat PowerPoint presentation for the prod

     I was doing some research on can we apply the conditional text in Markdown just like we do in DITA, and came across this: https://shopify.github.io/liquid/ https://shopify.github.io/liquid/basics/introduction/ Static Site Generators such as Jekyll can process Markdown and Liquid, and you can implement conditional filtering and content reuse using Liquid. I mean to say DITA is not the only go to implement conditional text. Related articles: YAMAL front matter in Typora Insert images in Typora Use markdown for your README Why I am gung-ho about Typora Author documents using markdown Using mermaid in markdown Do agile technical documentation using markdown Tool independent technical documentation Techniques for cost-effective technical documentation The ability to learn is the key to survival. We can learn faster by learning from each other.

     I am a fan of MS Word, and especially the DOCX format has formatting options that almost no other tool has. DOCX is much advanced than the DOC format. DOCX is XML-based and is an open standard. Most people ignore the ubiquitous MS Word and think that it is inferior to other authoring tools. It is very reliable, has a small file size, and is almost an all-in-one tool that allows you to design graphs and graphics. It has advanced formatting options, which very few others have.  You can refer to the following link to know the differences between DOC and DOCX formats:  https://www.folderit.com/blog/difference-between-doc-and-docx-which-should-you-use/ The SmartArt feature in MS Word is among my favorites. The following link helps you learn more about it:  https://support.microsoft.com/en-us/topic/learn-more-about-smartart-graphics-6ea4fdb0-aa40-4fa9-9348-662d8af6ca2c#:~:text=A%20SmartArt%20graphic%20is%20a,appearance%20of%20a%20bulleted%20list. I created a detailed profile document fo