Ask HN: What makes good documentation?
I'm about to release my first OSS project in a long while. I've been putting a lot of effort into the docs. Its super important for me that the docs are useful and clear.
In your opinion, what makes good documentation?
What does documentation need to have in order to be useful to you?
This is the documentation I'm looking to improve:
https://yelluw.github.io/Bootparts/documentation
Thanks for your feedback!
2 comments
[ 3.0 ms ] story [ 14.1 ms ] threadWithout getting into a long-winded rant about good docs, here are some things that you could do on your page:
Make it clear what your library adds over Bootstrap. There are a lot of similar sorts of things out there, and it isn't immediately obvious what yours brings to the table. Give an executive summary with concrete details of functionality in your introduction, i.e., "This adds better footers, calls-to-action, and useful templates for prototyping not found in vanilla Bootstrap".
Consider embedding the code snippets instead of linking to Github. If you want, embed the snippets as gists or similar, but linking out to Github is a little weird for what should be short example code.
Consider moving the component explanations above the FAQ stuff. It's hard to imagine that people will want to know if they can contribute code or money without having seen the actual product in use.
Best of luck!