4 ms·

If the documentation will be on a hosted site, I would recommend adding the ability for supplemental usage examples of the API provided by the community. Commen

If the documentation will be on a hosted site, I would recommend adding the ability for supplemental usage examples of the API provided by the community. Comments on php.net's documentation site and on apidock.com have been helpful for me in the past. Obviously, user usage comments are not always helpful, but sites sort the comments based on what other users find helpful. In my opinion, having the primary documentation with supplemental community supplied usage examples is the best way to do documentation.

steveklabnik 12y ago
It's been a while since I used PHP, but many of those examples are _very_ bad, and encourage very poor practices. I plan on having examples built-in with the documentation for everything, but actually approved by the team, rather than just as comments. They'll be much higher quality that way.
- mratzloff 12y ago
  One of the things I love about Go's documentation is that all examples are runnable in the Go Playground, right there, inline. You can take an example, modify it, and see how things change. Rust would benefit greatly from that same functionality. It also forces documentation to be up-to-date; one of the reasons I selected Go over Rust a year ago (besides more mature libraries and better documentation) was the fact that Rust seemed to be rapidly changing.
  - steveklabnik 12y ago
    Our home page already has this, go try it! http://www.rust-lang.org/ http://www.rust-lang.org/ > Rust seemed to be rapidly changing. Yup. That's what happens with a pre-1.0 language. :)
- mrinterweb 12y ago
  I don't disagree on PHP.net's user supplied examples being horrible at times. I thought that an example voting system would help regulate bad examples. Team approved examples could also be excellent. Does that mean users could supply examples and then moderators would approve the examples? I wish you the best luck with the new rust documentation and have well placed high expectations for what you will likely do with it.
  - steveklabnik 12y ago
    > that mean users could supply examples and then moderators would approve the examples? Yes, Rust is 100% open source, so anyone can submit such things. And thank you!

steveklabnik 12y ago

It's been a while since I used PHP, but many of those examples are _very_ bad, and encourage very poor practices. I plan on having examples built-in with the documentation for everything, but actually approved by the team, rather than just as comments. They'll be much higher quality that way.

mratzloff 12y ago
One of the things I love about Go's documentation is that all examples are runnable in the Go Playground, right there, inline. You can take an example, modify it, and see how things change. Rust would benefit greatly from that same functionality. It also forces documentation to be up-to-date; one of the reasons I selected Go over Rust a year ago (besides more mature libraries and better documentation) was the fact that Rust seemed to be rapidly changing.
- steveklabnik 12y ago
  Our home page already has this, go try it! http://www.rust-lang.org/ http://www.rust-lang.org/ > Rust seemed to be rapidly changing. Yup. That's what happens with a pre-1.0 language. :)
mrinterweb 12y ago
I don't disagree on PHP.net's user supplied examples being horrible at times. I thought that an example voting system would help regulate bad examples. Team approved examples could also be excellent. Does that mean users could supply examples and then moderators would approve the examples? I wish you the best luck with the new rust documentation and have well placed high expectations for what you will likely do with it.
- steveklabnik 12y ago
  > that mean users could supply examples and then moderators would approve the examples? Yes, Rust is 100% open source, so anyone can submit such things. And thank you!