Building Techscriptor - A Simple Tool For Technical Writers
Techscriptor.com is a free and open-source Markdown editor that makes your writing precise and clear.
Table of contents
Want to improve your technical writing? Are you able to captivate your readers? Do you keep your blog articles clear and readable?
If you are, like me, on the journey to becoming a better technical writer, this article is for you!
Project motivation
I have been reading tutorials on blogging and technical writing to improve my own skills. Many guidelines include checklists for making sure your content is clear. So, I thought to myself:
What if there was a tool to detect bad writing style?
That's how the idea for creating Techscriptor was born.
I wanted an online editor similar to Hemingway App but with a focus on technical writing using Markdown. My goal was to keep it minimal and super fast. Best of all, it's free and open-source!
What does it do?
The basis for Techscriptor's logic is Google's technical writing guide. You can easily avoid some common stylistic mistakes if you know what to watch out for, such as the following:
- Long sentences: Make your sentences short and clear.
- Passive voice: Use the active voice most of the time.
- Generic expressions: Reduce imprecise, weak, or generic words.
- Adverbs: Avoid adverbs if they add no significant meaning.
In the future, I would like to add more.
All of the mistakes are detected and highlighted in the editor as can be seen in the following picture.
How It Was Built
It's a simple architecture with HTML, plain JavaScript, and a few libraries. There is no build pipeline. You only need a web browser for viewing index.html. The webpage depends on the following libraries which are loaded from CDNs:
- Ace: an online code editor
- markdown-it and markdown-it-footnote: for rendering markdown code to HTML
- highlight.js: for syntax highlighting of code blocks
- Bootstrap: for general website design
Those are needed for displaying a markdown editor on the left and some rendered markdown on the right, along with syntax highlighting and footnotes.
Apart from that, I wrote a JavaScript function that detect stylistic mistakes and highlights them. For that, I used some good old regex, such as the following which detects adverbs: /((\w+)ly)|sometimes|perhaps|maybe/g (Note that it does not detect all possible adverbs but I guess a regex for that would be much more complex.)
Finally, the editor counts and summarizes mistakes to display an overview, as can be seen below:
Conclusion
This is how I made Techscriptor! I hope that you enjoyed reading the article and that there was something you could learn from it.
If you have feature requests or suggestions, please let me know!
- Would the editor help you in your process of writing?
- What else makes a good writing style?
- How can the tool be improved?
If you like to learn more about my project, check out the following links:
If you like this project, please share it and give it a star on GitHub!