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. 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. * 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. * 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? > 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. -- Pauli Virtanen --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
