8 ms·

On the flip side, does anyone you examples of projects with perfect documentation?

bluejekyll 9y ago
If this wasn't sarcastic, it probably should have been. There is no perfect documentation, because you can't predict your audience. I document code in such a way as to make it easier for myself to go back to it. I've kicked myself too many times to count where I didn't document something; went back to code, found it confusing, went to find out who wrote it only to discover it was me. Document your code for yourself.
- afarrell 9y ago
  If you are writing starting a project or writing it for yourself, this is great advice. If you aspire to have it used by other people, it is still good advice, but only a first step. The next step is to test the documentation. Have someone run through your intro tutorial and see both: - How hard is the tutorial to work through - How well does it help them build a mental model of the major interfaces of the project.
x0 9y ago
I really like the way (most of) PHP is documented. Every function gets a page, most of those pages get usage, examples and comments. However, when you go into some of the more obscure stuff, the documentation tends to just be function prototypes. So not perfect but I really enjoy it.
swashbuck1r 9y ago
This beautiful-docs repo has a list of higher quaility docs... https://github.com/PharkMillups/beautiful-docs https://github.com/PharkMillups/beautiful-docs
mattip 9y ago
NumPy [0] and matplotlib [1] both have well designed tutorials, specific function documentation, and integration with IDEs for Intellisense help while programming. [0] https://docs.scipy.org/doc/numpy-1.12.0 https://docs.scipy.org/doc/numpy-1.12.0 [1] https://matplotlib.org/contents.html https://matplotlib.org/contents.html
perlgeek 9y ago
PostgreSQL has very thorough and well-written documentation.
- petepete 9y ago
  Like with everything the PostgreSQL project creates, the documentation feels comprehensive, authoritative and solid. It's always my first port of call if I have a question. The one thing I'd like to see is more examples. Sometimes a quick demo of a function is all that's required for basic use.
mjw1007 9y ago
I think TeX came pretty close. I think the Exim spec is pretty much the gold standard for reference documentation, but they need a separate user-friendly introduction too (there was a separate paper book at one point).
baby 9y ago
Laravel is always praised for its documentation: https://laravel.com/docs/ https://laravel.com/docs/ I've heard that every comment in code follows the same pattern: every line becomes smaller and smaller. There is a lot of dedication in this project.
assafmo 9y ago
RabbitMQ, very easy to start in any language you'd want.
freshhawk 9y ago
SQLAlchemy docs are very good. I remember having to drop two layers of abstraction under the main API to get some very specific stuff done and it was still documented with useful example code. The actual software design is great as well, single-handedly changed my mind about ORMs.

If this wasn't sarcastic, it probably should have been. There is no perfect documentation, because you can't predict your audience. I document code in such a way as to make it easier for myself to go back to it. I've kicked myself too many times to count where I didn't document something; went back to code, found it confusing, went to find out who wrote it only to discover it was me. Document your code for yourself.

afarrell 9y ago
If you are writing starting a project or writing it for yourself, this is great advice. If you aspire to have it used by other people, it is still good advice, but only a first step. The next step is to test the documentation. Have someone run through your intro tutorial and see both: - How hard is the tutorial to work through - How well does it help them build a mental model of the major interfaces of the project.

x0 9y ago

I really like the way (most of) PHP is documented. Every function gets a page, most of those pages get usage, examples and comments. However, when you go into some of the more obscure stuff, the documentation tends to just be function prototypes. So not perfect but I really enjoy it.

swashbuck1r 9y ago

This beautiful-docs repo has a list of higher quaility docs... https://github.com/PharkMillups/beautiful-docs https://github.com/PharkMillups/beautiful-docs

mattip 9y ago

NumPy [0] and matplotlib [1] both have well designed tutorials, specific function documentation, and integration with IDEs for Intellisense help while programming. [0] https://docs.scipy.org/doc/numpy-1.12.0 https://docs.scipy.org/doc/numpy-1.12.0 [1] https://matplotlib.org/contents.html https://matplotlib.org/contents.html

perlgeek 9y ago

PostgreSQL has very thorough and well-written documentation.

petepete 9y ago
Like with everything the PostgreSQL project creates, the documentation feels comprehensive, authoritative and solid. It's always my first port of call if I have a question. The one thing I'd like to see is more examples. Sometimes a quick demo of a function is all that's required for basic use.

mjw1007 9y ago

I think TeX came pretty close. I think the Exim spec is pretty much the gold standard for reference documentation, but they need a separate user-friendly introduction too (there was a separate paper book at one point).

baby 9y ago

Laravel is always praised for its documentation: https://laravel.com/docs/ https://laravel.com/docs/ I've heard that every comment in code follows the same pattern: every line becomes smaller and smaller. There is a lot of dedication in this project.

assafmo 9y ago

RabbitMQ, very easy to start in any language you'd want.

freshhawk 9y ago

SQLAlchemy docs are very good. I remember having to drop two layers of abstraction under the main API to get some very specific stuff done and it was still documented with useful example code. The actual software design is great as well, single-handedly changed my mind about ORMs.