
Ask HN: What makes good documentation? - pryelluw
I&#x27;m about to release my first OSS project in a long while. I&#x27;ve been putting a lot of effort into the docs. Its super important for me that the docs are useful and clear.<p>In your opinion, what makes good documentation?<p>What does documentation need to have in order to be useful to you?<p>This is the documentation I&#x27;m looking to improve:<p>https:&#x2F;&#x2F;yelluw.github.io&#x2F;Bootparts&#x2F;documentation<p>Thanks for your feedback!
======
angersock
Thank you for releasing a project into the wild! :)

Without 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!

~~~
pryelluw
Wow, thanks for this feedback. It is exactly what I was looking to hear.

