5 ms·

It baffles me that all those JS physics library never provide proper docs or even an API reference and always link to the C++ Box2D manual as if it was an accep

by d0vs 9y ago

It baffles me that all those JS physics library never provide proper docs or even an API reference and always link to the C++ Box2D manual as if it was an acceptable alternative. Always have to guess what the JS equivalent is but even then you're in for a surprise: https://github.com/shakiba/planck.js/blob/master/CHANGES.md https://github.com/shakiba/planck.js/blob/master/CHANGES.md

RodgerTheGreat 9y ago
On one hand, I agree with you that linking to the documentation of another library, in another language, isn't very helpful. On the other hand, it's an open-source project. It has to start somewhere, and referencing the original docs is better than nothing. If you've looked at a variety of libraries along these lines and found them lacking, perhaps you're an ideal person to contribute better docs to this project.
franciscop 9y ago
As a dev of an unrelated lib who cares about making good documentation this is a really valuable comment; I'm guilty of doing this partially for example in https://github.com/franciscop/drive-db https://github.com/franciscop/drive-db where I link to MongoDB platform for the more advanced selectors. In my experience good documentation takes around 3x-5x of the time of writing the code (excluding tests and tutorials), so while I hate seeing libraries without a decent documentation I totally understand it. Edit: also it is in alpha, where writing documentation many times backfires you and you have to remove large pieces of it wasting your time.
- moron4hire 9y ago
  I've found writing documentation and trying to explain to others why the API is the way it is frequently makes me completely reconsider and redesign the API to be better. So no, you really should start on documentation right away, because what you're calling "waste" right now is a feature.
  - franciscop 9y ago
    That is interesting, I think the way I do it is quite similar: normally I write the examples that would go in the documentation first then work around it, but I don't write the whole text+proofreading which is what takes most of the time for me. Edit: see this "others" folder for example: https://github.com/franciscop/server/tree/master/others https://github.com/franciscop/server/tree/master/others
  - munchbunny 9y ago
    That does help, but I've found that getting people to try using your API does an even better job of informing you about your design decisions. Last time I was building a novel API, I opted to provide commented example code for documentation, recruited several members of the intended audience to try out the API, and just offered to answer questions directly. I wrote out actual documentation in preparation for the "official 1.0 release." At some point it comes down to choosing how to spend your limited time. Writing documentation isn't going to be a "waste," but it's probably not high ROI because your early adopters are likely familiar with the problem domain anyway.
    - franciscop 9y ago
      Oh cmon I never ever said writing documentation is a waste! What I mean is that writing the final documentation with all that implies before you even know what the API is going to look like is a waste. Though I agree with the parent, stubbing some docs to get a better feeling of what the docs look like is valuable.
munchbunny 9y ago
I'm guessing it comes down to "writing docs takes lots of time, and when you're a lean operation priority goes to making stuff work." I'm sure once the project matures it'll get a documentation pass, but the project is quite young.
shakiba 9y ago
Those are changes to internals, there are only few API differences which are explained on readme page. Anyway, I agree with you, a new API doc would be very helpful.
abetusk 9y ago
For me, an example is worth 10 pages of documentation. The documentation is good for reference but only after you understand the ideas behind it. One of the biggest criteria I have for using a library is whether they have a rich set of examples to draw from.
- franciscop 9y ago
  Good documentation has tons of examples! For me the gold documentation is jQuery. When I didn't know enough JS the beginning was cryptical but the examples below made it, when I was experienced I could just read the beginning for the footprint.
- fdsfsafasfdas 9y ago
  Conversely, after the initial struggle getting the ideas behind it, examples are worthless and documentation is king.
  - abetusk 9y ago
    Sometimes. Examples are good at giving concrete working code to use as a basis but they only express a few ideas. Documentation will let you understand the different pieces so you can build what you like. Both are beneficial for different scenarios. I find I use examples much more often but when examples fail, documentation is necessary.

by d0vs 9y ago

RodgerTheGreat 9y ago

On one hand, I agree with you that linking to the documentation of another library, in another language, isn't very helpful. On the other hand, it's an open-source project. It has to start somewhere, and referencing the original docs is better than nothing. If you've looked at a variety of libraries along these lines and found them lacking, perhaps you're an ideal person to contribute better docs to this project.

franciscop 9y ago

As a dev of an unrelated lib who cares about making good documentation this is a really valuable comment; I'm guilty of doing this partially for example in https://github.com/franciscop/drive-db https://github.com/franciscop/drive-db where I link to MongoDB platform for the more advanced selectors. In my experience good documentation takes around 3x-5x of the time of writing the code (excluding tests and tutorials), so while I hate seeing libraries without a decent documentation I totally understand it. Edit: also it is in alpha, where writing documentation many times backfires you and you have to remove large pieces of it wasting your time.

moron4hire 9y ago
I've found writing documentation and trying to explain to others why the API is the way it is frequently makes me completely reconsider and redesign the API to be better. So no, you really should start on documentation right away, because what you're calling "waste" right now is a feature.
- franciscop 9y ago
  That is interesting, I think the way I do it is quite similar: normally I write the examples that would go in the documentation first then work around it, but I don't write the whole text+proofreading which is what takes most of the time for me. Edit: see this "others" folder for example: https://github.com/franciscop/server/tree/master/others https://github.com/franciscop/server/tree/master/others
- munchbunny 9y ago
  That does help, but I've found that getting people to try using your API does an even better job of informing you about your design decisions. Last time I was building a novel API, I opted to provide commented example code for documentation, recruited several members of the intended audience to try out the API, and just offered to answer questions directly. I wrote out actual documentation in preparation for the "official 1.0 release." At some point it comes down to choosing how to spend your limited time. Writing documentation isn't going to be a "waste," but it's probably not high ROI because your early adopters are likely familiar with the problem domain anyway.
  - franciscop 9y ago
    Oh cmon I never ever said writing documentation is a waste! What I mean is that writing the final documentation with all that implies before you even know what the API is going to look like is a waste. Though I agree with the parent, stubbing some docs to get a better feeling of what the docs look like is valuable.

munchbunny 9y ago

I'm guessing it comes down to "writing docs takes lots of time, and when you're a lean operation priority goes to making stuff work." I'm sure once the project matures it'll get a documentation pass, but the project is quite young.

shakiba 9y ago

Those are changes to internals, there are only few API differences which are explained on readme page. Anyway, I agree with you, a new API doc would be very helpful.

abetusk 9y ago

For me, an example is worth 10 pages of documentation. The documentation is good for reference but only after you understand the ideas behind it. One of the biggest criteria I have for using a library is whether they have a rich set of examples to draw from.

franciscop 9y ago
Good documentation has tons of examples! For me the gold documentation is jQuery. When I didn't know enough JS the beginning was cryptical but the examples below made it, when I was experienced I could just read the beginning for the footprint.
fdsfsafasfdas 9y ago
Conversely, after the initial struggle getting the ideas behind it, examples are worthless and documentation is king.
- abetusk 9y ago
  Sometimes. Examples are good at giving concrete working code to use as a basis but they only express a few ideas. Documentation will let you understand the different pieces so you can build what you like. Both are beneficial for different scenarios. I find I use examples much more often but when examples fail, documentation is necessary.