Arindam Majumder

OpenAI

Community Picks is a section on daily.dev where our community members share the most interesting and valuable content they've discovered online. From insightful articles to handy tools, every post is a gem curated by our dedicated coomunity. To contribute to Community Picks, you need to have at least 250 reputation points, ensuring that only active and trusted members can share their finds.

Community Picks

Documentation is crucial for any project as it increases productivity, improves collaboration, and enables easier maintenance and code reuse. Tips for writing interactive documentation include starting early, considering the audience, structuring the documentation, adding examples, and keeping it concise and clear.

The Importance Of Documentation

Permalink What happens when you come across a project without proper documentation?

Permalink Why Documentation is Your Coding BFF?

Permalink Tips for Top-Notch Documentation

Here are my thoughts on writing a great documentation
Start with a Clear Structure: Organize your documentation with a logical structure, including a table of contents for easy navigation. Divide content into sections like setup instructions, usage examples, and FAQs to help users find information quickly.
Be Concise and Use Examples: Write in clear, concise language and avoid unnecessary jargon. Use practical examples to illustrate how to use your code or system, as this can significantly enhance understanding and application.
Keep It Up-to-Date: Ensure your documentation reflects the latest state of your project. Regular updates are necessary to maintain its relevance and usefulness, preventing confusion from outdated instructions or examples.
Solicit Feedback and Improve: Encourage feedback from your users and contributors to identify gaps, unclear explanations, or areas needing expansion. Continuous improvement based on user feedback can greatly increase the effectiveness of your documentation.
What else do you follow?

Great read! The main tips I gleaned from this (which I tend to forget/neglect):
<ul>
<li>Document on-the-go</li>
<li>Add examples</li>
<li>Make the document(s) user-oriented (i.e., based on the target audience)</li>
</ul>

This is a tortured issue for developers because the field attracts those not intimidated by mathematics. For some reason, education likes separating mathematics from its underlying logic, formally expressed and taught using arguments formulated in words because its original sage was this asshole Socrates who liked fighting with the rest of Athens to the point they made him drink hemlock tea, which produces overly arrogant mathematics wizards that can’t explain themselves and useless argumentative types that fear numeric abstractions.
Truthfully though, most development is not beyond the ability to use words to describe itself, people need to get over the mathematics fears and just learn to do it (having matlab do it is fine if what you are making isn’t something human life depends on, AI sucks at it still but soon it will be the way most people deal with math let’s be real).
AI prompt engineering promises the displacement of these types, good riddance and now maybe fewer great minds will be wasted as lawyers since they can argue with the AI to scratch their Socratic itch.

I agree that docs is super important. Developers come and go but the code base stays. Without proper doc, it will give a hard time for new devs or even old devs in the future.
I wrote about <a href="https://pr.nico.fyi/blog/advent-of-pull-request-best-practices-11" target="_blank" rel="noopener nofollow">what to look out for regarding documentation when reviewing Pull Request here</a>.