The documentation is good, but it seems the comments need more features.
If I look at the PHP docs, the comments are full of notes and such with tips/tricks, items of note, and general stuff to look out for. This is great.
When I look at the Yii api docs, they also have this, but it is also mixed in with a number of questions to clear stuff up. I think the comments should be primarily for notes, tips, and code examples.
Alas I am a hypocrite in the matter as I’ve asked questions on them. Unlike the forums, if that’s done, there’s no notification of a new post to anyone though, so it’s kind of useless for a quick clarification.
I’d suggest that perhaps the comment section for all documentation have 2 tabs, “Notes” and “Discussion”. That way interesting tips aren’t cluttered by other stuff. Actually, perhaps the “Discussion” section should simply link to a post thread set aside specifically for that page here in the forum. That way it would receive attention by being bumped whenever someone added something. The forum would need another section for “Documentation”. That section should be locked to new posts and only allow replying so it doesn’t get cluttered.
The other option anyone has is to simply ask a question in the forum, though I think it would be better to keep discussion on the documentation together. As these threads would be directly on topic, it would be helpful in refactoring the documentation and making it clearer. Without them, it would be difficult to find what needs to be clarified in the documentation by simply searching for similar topics in the forum.
Good idea? Bad idea?
(I’d also like an option to delete/edit comments and such, at least for, say, 30min after being posted)