Best Practises to make an awesome documentation for your code
Hello Dear Ambitious programmers ?? ! I'll tell you my own little story ?? ! When I was in my first year as a junior developer, on my professional workplace , I was asked to create a reusable react component that'll be used in different parts of the code.
After this, at home I find it enjoying to learn react and create helpers / reusable components in the same time , so an idea came to me : “ Why not share my own creative work with the beautiful community ?? ? ” , Is it enough to push my code in my github account ?? ? and say I did it ! Of course not ?? !
We invite the beautiful community to use our code, so we must give them an awesome documentation that represents well our work and instruct them to use the full potential of it.
We can't deny the importance of a good documentation cuz it's the facade of our work , there is two important things about code documentation that we must know before diving into details :
? The first thing is that in every project, the file who contains our main documentation is README.md, first time you heard about the extension "md" or you don't know much about it ? don't worry ?? !
? This will brings us to the second important thing ; that inside the README.md we write a markup syntax language similar to html, you're weak or strong in html ? it doesn't matter ?? !
I ensure you that you'll be able to put in your Readme the stylish documentation you want ! ... ??
You have a work that you want to share, it might be a library , a tool or any helper , I tried to be the most generic possible to help you take the best from this article.
This is the steps to follow that'll help you on your path of creating docs :
1 - Think about your catching phrases :
In the top of each your docs , you'll have to indicate a name of your work, either it's a library name, a helper or a tool, it must be a concise name that describes briefly your work, next to it put a small catchy description that reveals the soul purpose of your work , after this I recommend you to write an introduction where you'll explain where your idea came from and the issue that your idea solve and give generally the use cases of your work, it'll put the reader on the context and let him know about the usefulness of your work ,this intro is recommendable depending on what you're targeting, but there are cases where you may skip this phrase if you provide the doc to your small team who already knows the utility of your work ?? .
2 - Show the reader the structure of your doc :
Your documentation must be well organized, you must provide the reader the landmark to be able to locate himself through your beautiful docs . For the reason that the docs can be so long , it must be well structured and well divised in clear and concise parts. I recommend you to wirte out a table of contents where you indicate the important sections of your documentation , you can get some inspirations from different models of table of contents depending on the work that you're sharing , for example if you're developping a library, you'll notice that their doc structure have a lot of similarities , now I invite you to see this important sections that'll be really helpful for you on creating your own table of contents:
? Introduction :
We already spoke about this part on the previous paragraph, in addition of that I encourage you to add some sub sections in this intro depending on your context: to describe more your work, to show some insights of your RoadMap ??? (UpComing and existing features??), to provide readers some important links and sources ...
? Getting Started :
This section is aimed to initiate the " ?? how to use ?? ", if there are any prerequisites you must mention how to integrate them in a simple way, moreover you must provide a basic usage example of your tool/library to guide the reader in his first steps using your work, it must be concise and focused just on the basic setup of the work.
? Authors :
I guess that the title explains itself enough ?? ! If you're a team ?? , or just one individual ?? , this section must contain the contact list (name , pseudo , their social website links if they desire ...) of all the contributors and if it's a big team project when everyone has roles we can state them as well ?? !
领英推荐
? Licence :
There many many varieties ?? of licenses that deserves of course a special article from me to you dear readers ?? to present you the existed models of licenses depending your case , briefly in this section you must choose the license that suits well your motive of publishing and sharing your work either it's for commercial, personal use and whether you want claim your copyright rights ?? !
3 - Give demonstrations and explained examples :
People likes to see concrete results ??, by showing them demonstrations they will see concretely the result of our work and encourage them more to use it ??.
Providing examples with their correspondent output result will help a lot to learn quickly how they can use the work, linking examples with small explanations and dividing them through steps will guide well our dear potential user of our work ??.
It's even more simpler to navigate through examples when we have graphical illustrations & interactive contents such as screenshots, graphs, images, gifs or a website that interacts with the user ??.
4 - Consider about boosting your doc :
There are some small things that we can do to keep the interest of the readers ?? such as :
? Style of writing :
You can adopt many writing styles like "storytelling", you can choose a story (own or other) that fits in the context and narrate it to the reader ??, "speaking to the reader" is also a good writing style to always catch the attention of the reader, "showing emotions" when you're writing is also a wonderful technique because being humans we can send messages with each other through feelings ?? ( a small tip you can try using emojis ?? ).
? Using visuals :
You can describe what you're trying to say or show by using visuals like graphs, pictures, gifs or videos, those are good tools that catch the attention of the reader.
? Sharing resources :
Depending on your work, if you need to provide some extra information and you have important links, just add a section and share the links with their description to guide the reader through his journey of acquiring more knowledge on your topic ??.
Summing up :
Hooray now you reached the end of my article ?????? !!
I hope that you enjoyed reading my article and get some ideas to improve your writing skills for documentations.
I tried to give you the best I taught since I started writing docs, I would be really happy if you contact me and share with some of your own tips to get some of your new amazing ideas ?? !
Finally if you like my content and want to explore other articles, you are very welcome to visit my personal website ???: https://techmehdi.com/
This article: https://techmehdi.com/#/articles/101
Lead Software Engineer at Maltem Consulting Group
3 年I had fun reading your article especially, that reusable react component part ??