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! ❤️
I think some medium to large scale open source projects use docusaurus.
Even I want to start documenting my projects but ...
Ha!
😆
Thanks for the advice, I'll definitely read it
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
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
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/
This guide looks very interesting, today after work I'll definitely read it, thanks!
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.
Thank you very much!
Tried docz... Got stuck for days, tried docusaurus, 🎉🎉🎉 so so easy.
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.
Oh, I didn't know the Kruchten 4+1 approach. Seems interesting, thanks!
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).
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 🤞
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.
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.