You Are Doing It All Wrong — You Should Be Using a Word Processor to Create Markdown READMEs
Your Github repo has been sitting there for years, stagnant — nobody is interested in cloning it, let alone contributing to it. One reason might be that your README is poorly written. We’ve all been there. Maybe you are there now. Maybe you got lazy just because you think it doesn’t matter. Many Github authors rationalize that developers don’t look at README’s; they just start using the code. Wrong! It does matter.
We all agree that poor communication leads to poor first impressions. You never want to force the reader to reread passages or sections to find out what is really going on. You don’t want run-on sentences, sentence fragments that lack verbs, confusing use of apostrophes, or double negatives.
Everything needs to be clear. Your README needs to be as good as the project to which it refers to. The organization of your README needs to be logical and effective, engaging your audience, inspiring developers to start using it, explaining the clear benefits. You need to include sensible graphics that have lucid explanations that are attention-getting and compelling. You need to explain your repo in a coherent fashion, providing a gratifying reading experience that has a balanced approach and take appropriate advantage of tables, logos, lists, and outlines. You need to provide step-by-step instructions on how to install and use your repo. Inspire potential developers to contribute to it and use your repo, making it better and spreading its use throughout the open source community.
Making your README effortless is critical, so avoiding spelling and grammatical mistakes is very important. The key is to get developers to realize that your project is handy and that it offers a high-quality solution to the problem they are facing. A user-friendly description is key to the README. A high-quality README enables the developer to relaunch your project, without having to waste any time recalling what it was about or how it works.
The image below might shock you. What you are looking at is all the options provided by Microsoft Word. Any decent README will consider:
· Grammar
· Clarity
· Conciseness
· Formality
· Inclusiveness
· Punctuation
· Geopolitical References
· Vocabulary
The image below shows all the capabilities that are available out-of-the-box for Microsoft Word.
Your document would reveal the following Editor Pane in Microsoft Word. The image below analyzed one of the most popular repos on Github. It is a brilliant repo, but there is still room for improvement. The Github repo focused on Node.Js best practices. We stripped out the code which would throw off the statistics. Bottom line — some improvements could still be made across in the areas of conciseness, inclusiveness, and punctuation.
But you still have a problem. How are you going to get from Microsoft Word to Markdown syntax? It is a heroic effort. You need to take all the images, extract them from Word, and save them to disk. Tables need to be converted along with a bunch of other things, like hyperlinks, headers, bold, italic, strikethrough, highlight, and more.
There are only a few products that do a decent job. One of those applications that allow you to convert from Microsoft Word to Markdown is Pandoc, but that application has issues and is not really optimized to convert to Markdown. See the following article, https://medium.com/@info_27893/the-many-ways-markdown-converter-toolkit-for-word-excels-over-pandoc-e3676dacad75, The Many Ways Markdown Conversion Toolkit for Microsoft Word Excels Over Pandoc. Another more robust option is this product, https://www.microsoft.com/en-us/p/markdown-conversion-toolkit-for-word/9mx69nvzwvgd?activetab=pivot:overviewtab, Markdown Conversion Toolkit for Word.
