From Google Docs to Mkdocs: Reasons Behind Switching?

Welcome to the first post in my new blog series! 📝 I'm excited to share my journey as a tech writer, moving from using only Google Docs to exploring tools like Mkdocs.

At the beginning, I stuck with Google Docs for everything. But as my documents got bigger, I ran into problems, especially with keeping things organized and visually appealing. People told me they found it tough to find their way around long documents and got frustrated. So, I knew I had to find something better, and preferably free 😁.

So, I went searching and found Mkdocs. It's pretty amazing ✨ - it transforms your markdown files into a static website, all set to be launched online. Let me guide you through the process in more detail.

What is Mkdocs!?

Think of MkDocs as your helpful friend in the world of documentation. It's an open-source Python package that turns your plain markdown files into beautiful web pages. With MkDocs, you don't need to be a tech whiz to create a stunning website from your writing. So, instead of just having boring text, MkDocs gives your content a makeover to make it look fantastic online. 🌟

Advantages

• Open Source: Since Mkdocs is open source, you can contribute and customize it as much as you like. You can also check out plugins created and shared by the community here.

• Free Theming Styles: You have the freedom to customize your own theme or choose from a variety of great themes like "Material Theme" or "Read the Docs." Explore the full list of themes here.

• Organized Docs & Search: You can organize your docs however you want, making it easy for your readers to navigate. Plus, there's a handy search feature to help them find what they need.

• Supports Continuous Deployment: You can set up automatic deployment so that your site updates whenever you push any changes to the version control.

• Track Reader's Journey: Since Mkdocs is web-based, you can integrate tools like Google Analytics to track the journey of website visitors and even gather feedback from them. This can help understand how users interact with your documentation and identify areas for improvement.

Disadvantage

• Knowledge of Markdown Required: Using Mkdocs requires familiarity with Markdown, which may be a barrier for some users unfamiliar with this markup language.

• Limited Real-Time Collaboration: Unlike Google Docs, Mkdocs lacks real-time collaboration features. If multiple people need to work on the same document simultaneously, Mkdocs may not be the ideal choice.

• Customization Complexity: Achieving highly customized edits in Mkdocs may require assistance from external developers or seeking help on platforms like Stack Overflow and the open-source community.

Google Docs

Advantages

• Real-Time Collaboration: One of the biggest advantages of Google Docs is its real-time collaboration feature. Multiple users can edit a document simultaneously, making it ideal for teamwork and group projects.

• Cloud Storage: Google Docs is cloud-based, allowing you to access your documents from any device with an internet connection.

• Collaboration Tools: In addition to real-time editing, Google Docs offers collaboration tools such as comments, suggested edits, and chat, facilitating communication and collaboration among team members.

Disadvantages

• Formatting Challenges: While Google Docs offers a variety of formatting options, achieving complex layouts and formatting can sometimes be challenging.

• Navigation Challenges with Large Documents: As documents in Google Docs grow larger, users may experience frustration when navigating through extensive content. Finding specific sections or information within a lengthy document can become time-consuming.

• Dependency on External Links for Rich Media Content: Incorporating multimedia elements such as gifs, videos, or external content in Google Docs often requires users to refer to external links. This can lead to some distraction for readers.

When you can use Google Docs instead of Mkdocs?

If you're just writing down a basic task and don't plan on making many changes or needing fancy formatting, and your document is short and sweet, Google Docs works fine. It's easy to use and good for quick jobs without getting too complicated.

---

My Research Outcome

After conducting my research, it's clear that I'm on the Mkdocs side! Here's the list of tools I've decided to use:

• Code Editor: Any code editor will work for writing markdown files, but I've chosen VS Code. It offers many extensions that make writing markdown easier and more efficient.

• Version Control: I've decided to use GitHub for version control. I'm already familiar with it, and I've configured GitHub Actions to automatically generate and publish a new version whenever I push any changes to the main branch.

• Mkdocs Theme: For the theme, I've chosen Mkdocs Material Theme. It offers a wide range of features and customization options, making it an excellent choice for my documentation needs.

Concolusion

In wrapping up, my transition from Google Docs to Mkdocs has been a real eye-opener. While Google Docs is fine for simple tasks and short documents, Mkdocs takes the lead when it comes to managing larger documents. Its features and capabilities outweigh those of Google Docs in many respects, making it the preferred choice for more extensive projects.

Comments

[johnblommers]

My guess is that Mkdocs includes no spell checker. That would be included in the Markdown editor one uses.

[Khaled Abdel-Fattah]

Hey @johannes_k_rexx

Just wanted to share a solution I found helpful for that problem - using the "Grammarly" extension in VS Code. It worked well for me and sorted out my issues. Give it a try from here