Introduction
These days nobody prefers any project or code that is not well-documented. In a project, documentation increases readability, guides the user to get a clear idea about the project, and also helps a developer to understand it well and work on it. So, here I am with the key points and tips for writing documentation.
Let's dive into it !!
What happens when you come across a project without proper documentation?
Suppose, You're a new developer on a large project, and you dived into it with full enthusiasm and excitement to find yourself surrounded by complex functions, and big lines of code that you need to analyze as a whole to understand and work on.
This is the problem that we, developers face when we get a project without proper documentation. And that's where documentation plays a crucial role in making it more accessible to the users.
In the next section let's explore how documentation helps us.
Why Documentation is Your Coding BFF?
Here are some points on how documentation helps us.
Increased productivity: Clear Documentation helps to understand a project easily. Thus investing minimal time in understanding and analyzing it saves time and energy
Improved collaboration: Proper documentation helps in better communication within your team. It keeps everyone on the same page making the project workflow smoother.
Easier maintenance and updates: When we understand the code, fixing bugs and adding features becomes easy. Documentation acts as a roadmap, guiding us through every part of the project. And thus it makes it easy for the maintainer to maintain the code.
Reusable code: Well-documented code is easier to reuse, which saves our time and effort.
Now you have an idea of why documentation is crucial for any project. But here comes the real question, how do you make your documentation more interactive, user-friendly, and useful?
Let's look at some of the tips for making documentation.
Tips for Top-Notch Documentation
Here are some of the tips for writing interactive and useful documentation.
Start early and stay consistent: Don't wait until the code's finished to document it. Document the code throughout the whole process of writing the code and be consistent in that.
Write for your audience: Consider who will be reading the documentation. Are they coders or newbies? Modify your language and explanations accordingly. Your documentation should be user-oriented.
Structuring the documentation: Use headings, subheadings, and bullet points to break down information into digestible chunks. Nobody likes a wall of text, not even programmers.
Adding all actions: Add all the commands your product uses in your documentation.
Adding some important elements: It always serves as +1 if you add a table of contents, terminologies associated with your project, installation process, and tutorials.
Adding a search button makes it more customizable.
Adding Examples: Illustrate your explanations with code snippets and diagrams. A picture (or code) is truly worth a thousand words. This also makes your documentation interactive.
Keep it concise and clear: Avoid overly technical terms. It should be easy enough to understand by users, developers, or programmers.
Here have a look at one of my tweets on documentation:
.
Now here after following the tips we are ready with presentable documentation. Finally to give an ultra edge to the documentation here are some of the key points.
Key Points to Keep in Mind:
Focus on the "why" as much as the "what." Explain the purpose and reasoning behind your code.
There are plenty of documentation tools available, from simple Markdown editors to API generators. Find one that fits your workflow and use it.
Be clear about the user goals and learning objectives (intellectual goals). To achieve user goals you must take care of some learning objectives.
Write your docs as code as editing code is easier.
Most importantly, have fun! Inject your personality and passion into your words, and you might create documentation that people enjoy reading.
Conclusion
Remember, to keep your documentation updated because that is the entry point of your project.
Also don't forget to add pictures, GIFs, or even fun facts to your documentation. A little visual flair can go a long way in keeping your readers engaged.
If you found this blog useful and insightful, do consider sharing this blog and comment down your views on it. Do follow for more such content.
Here's how you can connect with me.
Email - olibhiag@gmail.com
Socials: <Twitter><LinkedIn><GitHub>
Thanks for giving it a read !!
Wish you a happy journey for your coding and documenting.
Top comments (14)
I'm a @get_pieces user too. I just love its performance. Specially using GPT4 !!
Happy you are loving your experience so far! 💃🏼
Thanks for the mention! 🤩
That's an amazing article! Congrats!
I'm working as Technical Documentation Analyst, here in Brazil, and I see how important is to document everything we do. Now, I work writing manuals but, before, I used to work with the internal technology team. There, I needed to use every knowledge I had so I could write to dev but also to someone who doesn't have a dev background.
Now, as I'm studying to become a dev, I see how important it to be able to share all the technical knowledge with a good documentation.
Thank you so much for this article. I'm sure it's going to help a lot of people!
Glad you liked it !!
Thanks for reminding us to the importance of documentation. Another possible bulletpoint is: Reminding ourselves how the code works.
We probably went all through the painful process of re-opening a project of years ago. Unless you have an elephant memory it goes like Did I write this? Never mind finding the bug or the insight to update or add new features.
We learn. We improve. Languages evolve. New techniques/frameworks. We outwit ourselves at times. Even international acknowledged standards change (may/must/should/...).
To the point of embarrassment of What the heck was I thinking? I guess it's normal. So I started documenting code... for myself. At first.
Last but not least. What happens if you sell a project/website? My guess is, a well documented (private) project augments the value thereof.
Thanks for sharing your POV !!
Nice post
Glad you liked it !!
I'm finding that just keeping a daily journal in Markdown using MindForger has strong benefits later on. The Markdown files have a much better memory than my brain does.
And after a few years it's amazing how much knowledge one accumulates in a journal.
Given recent developments in self-hosted large language models (LLM) I'm looking forward to exploring locally hosted LLMs so I can have discussions with my multi-year Markdown journal.
Nice, great article!
Thanks !!
Glad you liked it