Documentation in Software Projects with MkDocs

Documentation in Software Projects with MkDocs

Words fly away, but writing remains.

When we start a project, our priority is often technical matters. Should we use this framework, this architecture, this pattern, etc.? Or we focus directly on coding the processes.

As our ancestors wisely said, "Words fly away, but writing remains." We do a lot of work during development. We add parameters, make configurations, develop a utility. But most of the time, the general knowledge of what we've done remains with the person doing it. When maintenance is needed, we try to find solutions by rereading and understanding the code. Or sometimes we even redo something that already exists.

Frankly, I don't personally like Office tools for technical tasks. I always get the feeling they're written with the mindset of "let's just write this document and get it over with."

So, what if we documented what we did? What does documentation provide us with?

• First and foremost, it paints a big picture of the project. Looking back, it shows what was done, what kind of architecture was designed, what standards were in place, etc. It gives us insight into many aspects of the project.
  
  
• It allows someone new to the project to adapt quickly.
  
  
• It helps us define project standards.
  
  
• It allows us to see what and how the developed tools work.
  
  
• It shows that the project was developed/maintained according to specific rules.It ensures standardization.

We could say many things like this. Yes, we want to write documents, but sometimes we don't know how to start. Or we struggle to determine what kind of headings should be included in this document. Or we don't know what tool to use to write this document. I've seen people trying to write technical documentation with tools like Word and Excel. Frankly, I don't personally like using Office tools for technical topics. I always get the feeling that they're written with the mindset of "let's just write this document and get it over with."

At this point, I can recommend the MkDocs tool. MkDocs allows us to write documents in markdown format. It exports the written documents as static websites. It also provides theme support; you can change the theme of the exported website. You can also export to different formats like PDF.

MkDocs is a tool developed with Python, so you will need a Python installation.

So, what headings could be included in the documentation? To give you an idea, it could roughly be something like this:

• Project Overview
  
  
• Architecture
  
  
• Backend/Frontend technologies
  
  
• Code organization; package structures
  
  
• Development standards, writing styles
  
  
• Features and usage of developed libraries
  
  
• Deployment processes

You can vary these according to your needs, like the headings here.

Installation

pip3 install mkdocs

Creating and running a sample project

python3 -m mkdocs new my-project

pip3 install mkdocs-material #metarial tema kurulumu için

cd my-project

set/export ENABLE_PDF_EXPORT=0s

python3 -m mkdocs serve --dev-addr=localhost:9003

Static Web Site olarak export etme

python3 -m mkdocs build

And the result…

Once the project is created, a file and a directory are generated.

The “mkdocs.yml” file allows us to write the menu tree.

I've created a sample project for you to examine in detail; you can access it here.