Pauli Virtanen schrieb: > Sun, 22 Mar 2009 16:41:26 +0000, Wojtek Walczak wrote: > [clip] >> Assuming that I will do something similar to what I see at Django Book >> site, I wonder now if we couldn't mix comments and "change suggestions" >> features together. In both cases we should provide a way for developers >> to discuss the suggestions and to accept or reject them. >> >> What about adding some attributes to each comment, like: >> >> - type (typo or missing sign / grammar or style problem / wrong >> description / bad code / proposal) >> - status (open / accepted / rejected) - priority (low / normal / high) >> >> Then we could use different colours for the baloons (as it is called in >> Django Book) to indicate the kind and state of a problem. There may be >> many different comments under a single baloon with various types, >> statuses and priorities, so the colour of the baloon should rather tell >> us if there is any open comment for particular block and what's the >> priority of a comment. I imagine that we could use three tones of red >> (each indicating different priority) for open comments, and some other >> colour if there is no open comment. > > Tagging comments seems like a good idea, and if looked in this way, I > don't think the change suggestions need to be separated.
I still like to separate them. There might well be a "change suggestion" comment type (for those who don't want to use/find the suggestion method), but it is much more work for a developer to extract a suggestion from a comment than to accept a diff. Also, if you only let people comment on the text, they might say "here the effect of parameter *foo* should be documented". If you let them edit the text proper, they might go all the way and add a sentence or two that's already good to commit. Ergo, less work for the developer again, and also less work for the submitter than getting the source locally, editing it and submitting a diff to the Python tracker. > But for the developer, clicking through the change suggestions via the > Django-Bookish UI seems quite clumsy. From this POV, it would be useful > to also have a report view where one could browse through all comments, > filtered by the tags (eg. change suggestions, typo), and categorized by > file. > > Some other miscellanous thoughts: > > * Re: comments -- it's probably useful to look at what people are > submitting to the php.net docs, to get an idea what the comments can > (will) be used for. It seems there's demand for code snippets, extended > explanations of some points etc., so it may be good to ensure that > people can add these things easily. > > * One related usability question: if the comments are hidden such as in > the Django book, does the user need to separately click every one of > them open to find out whether there's something interesting in one of > them? So a mass-expand feature or some other way of listing all of them > would be useful to have. Only if you read the text top-down, like a book. On pages like a library reference, you're usually only interested in comments to the one or two functions you're reading the docs for. Of course, a mass-expand button isn't very hard to do. > * Also, a comment policy probably needs probably to be set: ensure that > what the users submit in there can legally be incorporated as a part of > the documentation itself... In the possible event that the submitted > stuff is good. That's a good point (for change suggestions, not comments). Perhaps a simple notice like on Wikipedia edit pages suffices. > * What about the position of the comments when the underlying document > changes? What to do with comments that refer to a position that's no > longer there? Another good point, let me elaborate a bit on what has already been done in one iteration: Comments could be attached to whole pages and to descitems (functions, classes, so on). That way, they could only be "lost" if a whole page was removed, or if a descitem was removed, which usually also means that the thing documented was removed, and so the comment doesn't apply any more. >> But the question arise: who should be able to change the status or >> priority of a comment? Everyone or only logged in users? > > I'd restrict changing status to the original submitter and the developer > only. But this leaves the question open what to do with anon users. Anonymous submitting is bad: too much work for the developers sorting out spam and other useless junk. Using e.g. OpenID would be nice. Georg --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "sphinx-dev" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en -~----------~----~----~----~------~----~------~--~---
