DEV Community

Cover image for A good documentation can lead you to be better
Michelle Mello
Michelle Mello

Posted on • Updated on

A good documentation can lead you to be better


I'm sure you've encountered a lot of documentation in your life, whether it was for studies or work. Even your mom probably already read documentation on how to change her profile picture on Facebook! But have you ever considered the importance of writing your own documentation?

Creating your own documentation can help you retain the information you're learning. Write it as if you're explaining to someone else what you're studying.

It's not an easy task, but this exercise will engage your brain and help you fix the knowledge you've acquired. Imagine this: one day, you ask a senior developer about a function in the code you're working with and they explain how each component works within the code. Now, fast forward a few days, and you need to revisit that part of the code but you have forgotten how it works. Wouldn't it be better if you had a documentation to support you?

Documentation is an important step, you'll be showcasing how much you know and how much care you put into your code and work. And now, I'd like to share a few tips that I use when I'm writing:

Write first and edit later

You know when you are studying or coding and you think about everything all at once? Write it down! Don't worry about whether it's right or if it makes sense. Just write. Put your thoughts into words.

After you finish, give it some time, like 30 minutes or 1 hour, and then come back to it. Read it and see what you can improve. Repeating this will help you to improve your writing skills. Trust me.

Pretend you're explaining it to someone unfamiliar with technology

When writing and trying to explain something, imagine that you are talking to someone who doesn't understand how technology works. This will help you think of the best ways to communicate what you mean, maybe it'll be through texts only, or maybe it'll be clearer if you add drawings, images, videos, etc.

As technical writers, we need to ensure that everything we write is easy to understand, regardless of the reader's level of expertise.

Keep it organized

There are a bunch of tools, like Notion or Obsidian, that can help you stay organized with all the content you are going to produce. They will help you find the information you are looking for in an easier way. Do a bit of research before you start and try different tools at first. You can learn how you can use the tools and the best way to organize your content, like links between contents, tags, folders, and others.


Good writing doesn't come easy. It's an exercise, and every day we all improve a little. But I dare you do it anyway! You'll find it becomes easier every day and in the future you'll be thankful for starting it.

Now, tell me, do you already write about the things you develop or study? If yes, how do you do it? If not, are you interested? Let me know, and let's exchange experiences.

Thank you for reading and see you soon!

Cover image by pch.vector from Freepik.

Top comments (6)

fernandafmsf profile image
Fernanda Fernandes

Writing helps us to understand what we are studying better, and it also helps other people! I always had the habit of writing down what i study, but just for me. Now I am creating articles and it has been an incredible ride. It is hard to do it, especially in the beginning, but it is so worth it!
Nice article!

_michellemello profile image
Michelle Mello

That's so amazing! I'm the same way. I want to write more and more about my studies. Especially taking everything I learned as a technical writer and putting it into my studies to become a full stack developer. Hope to read your articles.

clintonrocha98 profile image
Clinton Rocha

Great to see the spread of this good practice, even more so with this simple and easy to understand explanation, I loved the examples and analogies (I love analogies hahahaha), congratulations on the article, hope to see more of your content here. 💜

_michellemello profile image
Michelle Mello

Thank you so much for your kind words!!

steeve profile image

I agree that you don't write only for people but also for a future version of yourself. Regularly writing is good for memory, and you gain skill at vulgarising information. Explaining in Layman's terms difficult concepts shows how much we integrated it.

_michellemello profile image
Michelle Mello

Good example. Understand Layman's terms can be so helpful. Thank you for your commentary!!