4 ms·

Ask HN: Good open-source software documentation examples

13 points by oktomus 7y ago

Hi ! I'm doing some research on how to improve/make appleseed[1] documentation. Appleseed is an open-source rendering software and we need both user and developer documentations such as: - Guide on how to use appleseed - Detailed docs on how appleseed is working - Developer documentation (API reference, contribution guide, getting started) So if there is a documentation that you really like, please share it :)(whether it's about rendering or not, for user and/or for developers) [1] https://github.com/appleseedhq/appleseed/

billconan 7y ago
I always recommend http://doc.qt.io/ http://doc.qt.io/ btw, appleseed looks nice. I'm looking for a ray tracker that can render typical 720p indoor scene under 15 seconds. (similar to https://appleseedhq.net/img/renders/bedroom-2.jpg https://appleseedhq.net/img/renders/bedroom-2.jpg) Can appleseed do that (this will need hardware acceleration I think)?
- oktomus 7y ago
  I also think qt doc is great. Yes, appleseed can do that ! But it will be really noisy :D Don't hesitate to come on appleseed's discord server if you need help.
springogeek 7y ago
Although it isn't perfect, I put a lot of effort into the docs for my game development framework at https://domeengine.com https://domeengine.com. Make sure each document/page has a clear audience, and it's clear to the reader what that audience is, as well as where other audiences should go.
- oktomus 7y ago
  Nice work !
tonyedgecombe 7y ago
I’ve been very impressed with the Django documentation.
marzer 7y ago
I've poured a lot of time and effort into documenting my C++ TOML library, generally seeking to write the docs as I would wish to find them if I were a new user: https://marzer.github.io/tomlplusplus/ https://marzer.github.io/tomlplusplus/ The docs are built using a spin-off of the documentation generator for the magnum graphics engine, which are themselves a really good documentation example: https://magnum.graphics/ https://magnum.graphics/
JoeMayoBot 7y ago
Here's the Wiki to my open source project, LINQ to Twitter: https://github.com/JoeMayo/LinqToTwitter/wiki https://github.com/JoeMayo/LinqToTwitter/wiki Same qualifications at others - not perfect. :) I've been maintaining the docs for several years. When people seem to be confused about a particular subject or are asking questions in a certain area, it's an indication that I need to work on that area more. Over time, I've noticed a relationship where targeted improvements reduce my support requirements. Feedback is welcome.
- oktomus 7y ago
  Thanks for sharing !

13 points by oktomus 7y ago

billconan 7y ago

I always recommend http://doc.qt.io/ http://doc.qt.io/ btw, appleseed looks nice. I'm looking for a ray tracker that can render typical 720p indoor scene under 15 seconds. (similar to https://appleseedhq.net/img/renders/bedroom-2.jpg https://appleseedhq.net/img/renders/bedroom-2.jpg) Can appleseed do that (this will need hardware acceleration I think)?

oktomus 7y ago
I also think qt doc is great. Yes, appleseed can do that ! But it will be really noisy :D Don't hesitate to come on appleseed's discord server if you need help.

springogeek 7y ago

Although it isn't perfect, I put a lot of effort into the docs for my game development framework at https://domeengine.com https://domeengine.com. Make sure each document/page has a clear audience, and it's clear to the reader what that audience is, as well as where other audiences should go.

oktomus 7y ago
Nice work !

tonyedgecombe 7y ago

I’ve been very impressed with the Django documentation.

marzer 7y ago

I've poured a lot of time and effort into documenting my C++ TOML library, generally seeking to write the docs as I would wish to find them if I were a new user: https://marzer.github.io/tomlplusplus/ https://marzer.github.io/tomlplusplus/ The docs are built using a spin-off of the documentation generator for the magnum graphics engine, which are themselves a really good documentation example: https://magnum.graphics/ https://magnum.graphics/

JoeMayoBot 7y ago

Here's the Wiki to my open source project, LINQ to Twitter: https://github.com/JoeMayo/LinqToTwitter/wiki https://github.com/JoeMayo/LinqToTwitter/wiki Same qualifications at others - not perfect. :) I've been maintaining the docs for several years. When people seem to be confused about a particular subject or are asking questions in a certain area, it's an indication that I need to work on that area more. Over time, I've noticed a relationship where targeted improvements reduce my support requirements. Feedback is welcome.

oktomus 7y ago
Thanks for sharing !