DEV Community

Alex Shulaev
Alex Shulaev

Posted on

How do you document your side projects?

I want to write a page with examples of use and documentation of my small side project. Who designed such pages? What did you use? Or maybe you know someone who makes very handy documentation for their projects and you learn from him? 🙂 I want to see examples of handy documentation for small projects. Thank you all and have a nice day! ❤️

Top comments (16)

Collapse
 
midasxiv profile image
Midas/XIV

I think some medium to large scale open source projects use docusaurus.

Even I want to start documenting my projects but ...

Collapse
 
adam_cyclones profile image
Adam Crockett 🌀

Ha!

Collapse
 
alexandrshy profile image
Alex Shulaev

😆
Thanks for the advice, I'll definitely read it

Collapse
 
_garybell profile image
Gary Bell

Documentation, on side projects? Nah!

That said, the one I am working in now will make use if the wiki feature of GitLab. Just seems to be logical and for the intended purpose.

My next one will probably end up with it's own full site and have articles/faqs/tutorials

Collapse
 
alexandrshy profile image
Alex Shulaev

My desire is connected more with training, in order to understand the process of creation and the number of resources spent on this, so that I can plan for the future

Collapse
 
patarapolw profile image
Pacharapol Withayasakpunt • Edited

The idea of doctest borrowed from Python, is helpful to both documenting examples, and up-to-date testing.

I have seen documentation websites generated automatically from JSDoc or JavaDoc as well, but I don't think they are always well-tuned. A better way still remains to be manually writing them.

About how to do open-source projects well, I am learning from opensource.guide/

Collapse
 
alexandrshy profile image
Alex Shulaev

This guide looks very interesting, today after work I'll definitely read it, thanks!

Collapse
 
giologist profile image
Gio

Docusaurus and GitBook are the more popular competitors at the moment. They're both great, so imo it just comes down to preference between them.

Collapse
 
alexandrshy profile image
Alex Shulaev

Thank you very much!

Collapse
 
adam_cyclones profile image
Adam Crockett 🌀

Tried docz... Got stuck for days, tried docusaurus, 🎉🎉🎉 so so easy.

Collapse
 
gwutama profile image
Galuh Utama • Edited

Regardless of side project or not I try to document the architecture using Kruchten 4+1 approach. It has helped me a lot to let others understand the big picture. For small projects I try not to describe the architecture too detailed.

Class and method docs can be automatically generated by different tools depending on language: sphinx, jsdoc, javadoc, doxygen, etc.

On the code level, i.e how to use this particular class or method, unit tests provide good examples on how to do that.

Collapse
 
mx profile image
Maxime Moreau • Edited

Oh, I didn't know the Kruchten 4+1 approach. Seems interesting, thanks!

Collapse
 
stereoplegic profile image
Mike Bybee

It's been forever since I used javadoc (or Java, outside of a few Android tweaks here and there), but I do recall it having the @example tag like JSDoc (not that you shouldn't be writing tests).

Collapse
 
martinbelev profile image
Martin Belev

Hi,

Recently we made an investigation because we are going to start a documentation site and I have made some research. You can check it - dev.to/martinbelev/what-are-you-us...

We chose Gatsby with Docz extended theme, there is more information why in the link. If you are using React, I would recommend it - pretty quick start, the theme gives you layout so that you are not loosing much time to do everything from zero, easy to deploy, customizable. It’s not a comprehensive list but it gives some idea.

Hope it helps and it will be interesting to share what you are going to use. Good luck 🤞

Collapse
 
corentinbettiol profile image
Corentin Bettiol

I used wiki feature a lot, and now I try to give enough information in the code (comments, tests) on how the project is supposed to work, and I fill the readme with other information (how to install, how to launch, structure of the project, contributing...).

I might try something like readthedoc for biggest projects. For very small things I write something in a gist, in order to be able to edit it if necessary.

Collapse
 
crimsonmed profile image
Médéric Burlet

Markdown, GitBook or Google Sites if there is multiple people on the project.
Google site has the easy sync with drive to include pictures, pdf and more if you are doing a large project.