re: What do you expect from a good documentation? VIEW POST


Props to you for picking up a documentation project! I originally wrote a comment got uncontrollably long, so I put it in its own post:

I think you can do a lot with just markdown on GitHub, and it's easy to convert the Markdown into HTML if you decide you want to put it on its own website.

The best place to start contributing to documentation of a project that is new to you is usually by smoothing out the "getting started" section and writing guides that would help other beginners build some simple applications using the framework. I'd suggest you try doing a small project using the framework and take careful notes at every step about what you're doing so that somebody else could follow along by just copy-pasting. You can easily turn this into a guide for new users.

Most people coming to a framework are total beginners in it, so writing for other beginners from a beginner's perspective is immensely valuable. People with more experience in the project may actually have trouble seeing from a beginner's perspective so they usually really appreciate this type of contribution.

Good luck with your project, and please update us on your documentation journey!


Hi, Eli! I am coming back from your original post. It was as informative as it was inspiring. I am not sure if I would be using anything but vanilla markdown. In all honesty, I would prefer using just that, at least for the first couple of such projects.

Given all the learning curves involved with the core project and the act of documenting it, I doubt if there would be any room left for learning documentation tools. So it was a sigh of relief when you suggested it's okay to do that.

I will make a detailed post about the documentation project and how it goes. (A documentation about documentation. How meta!). Would love to hear your constructive criticism on that!


I look forward to reading about it! There are so many documentation tools, but the content is the most important part anyway. I love the simplicity of Markdown.

code of conduct - report abuse