|Adding comments to the client protocol documentation
||[Mar. 19th, 2003|10:01 am]
LiveJournal Client Discussions
Most client authors willl recognise that the client protocol documentation is, shall we say, "slightly desynched" with the actual status of the protocol. Most will also recognise that it's going to take a significant effort for one person to go through and correct it.|
Can I therefore suggest that something similar to the comments system for the PHP documentation is put in place? (see http://www.uk.php.net/manual/en/function.printf.php for an example). This lets users post notes and errata to the documentation, and can generally answer most of the questions that arise.
Of course, it also leads to some misguided comments from users who don't completely understand what they're posting about, therefore I'd suggest that any such system used for the LJ CSP be moderated.
Thoughts/ideas? Has this been proposed/done before?
2003-03-18 11:24 pm (UTC)
Sounds like an overkill.
I may be a little overly optimistic, but I don't think the documentation is that horribly outdated.
Perhaps underdocumented in a few places, but not actually wrong in many.
The best way to quickly fix its deficiencies is to open a Zilla item with a detailed description of what's wrong in the docs, and I'm sure a documentation patch won't be long after that.
I'm not claiming that it's "horribly outdated", but following lj_clients
, and trying to use the docs myself, make it clear that there are certain errors, and places where the docs aren't clear. The PHP comments are good, for example, for adding notes that people wouldn't normally think of putting in the documentation, but are nonetheless useful.lj_clients
serves as a very useful forum for this sort of comment/note/correction, but there's no way of linking from the CSP docs to the relevant posts in this journal. Maybe some such linking mechanism would help, but I don't see how that would work.
If Zilla is the way forward, perhaps there should be a note to that effect on either the community's userinfo page, or the CSP documentation. (And if there is one and I've missed it, my apologies).
I like the idea. Rather than clogging up Zilla with bug reports for documentation issues (which most people won't bother with if the item is minor, or if they are lazy, or if they didn't even know they were supposed to file a bug) the documentation could be annotated and a maintainer can come by once in a while and use the comments to fix the docs.
The docs are outdated, there is plenty of useful info that isn't in there, and the current system to update them is way too cumbersome.
Ok - first dumb question, what's a wiki?
Apart from that, it looks like only benzado and myself are interested in getting this thing started, but I suspect more people will actually use/read it once it's running.