What do you think about being able to add comments to the rust book?


#1

I’m a beginner who is really fascinated of the concepts of rust, but at the moment I find it pretty hard to find any proper documentation on how things work in detail. I know that that is going to improve a lot until Rust hits 1.0 final, but I think it’d be great to be able to add comments to the pages of the official rust book.

That’s one thing (and probably the only :smiley:) thing I loved about php: Reading all these comments of people trying to help you out with some tiny tipps and tricks. Of course those people could as well just change the book, but I’m pretty sure that there are people who just want to leave a quick comment without having to make a pull request. Furthermore there are things that probably don’t even fit into the format of an official documentation book.

What do you guys think about this idea?


#2

I’m not sure I’d be for it. The issue I see is that PHP is very focused on being batteries included, while Rust seems to focus on having a solid library ecosystem to draw from. I’d expect the set of community-recommended libraries and practices to change over time, which clashes a bit with simple user-comments that can be out of date. It also can get messy once documentation is refactored.

Though I do understand the sentiment of making it easier for people to contribute documentation. A simple first step might be to make the current way easier, like linking from the documentation page to the relevant pieces on Github so the amount of clicks is minimized. By “simple” of course I mean the visual/workflow change. Actually doing it might be more involved than I’m aware.


#3

It has been quite a while since I’ve done significant PHP work, but at the time, those comments seemed convenient, but often were full of really, really bad advice. I am all for improving docs as much as possible, but I’m not a fan of adding comments.

@phaylon , I would agree that that might be better, and it actually would not be too difficult, just lots of manual work keeping the links from breaking.


#4

Would some form of easy feedback option be interesting? Not show them as comments, but make it supersimple to file issues for paragraphs?


#5

Yes, that might be neat.