Pauli Virtanen napisał(a): > 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.
Fully agreed. I think that I have to look at every piece of this project from two perspectives: (1) a person who only wants to read the docs and (2) a developer, who wants to browse the comments in most efficient way. The user should be allowed to read the docs without being too distracted by the comments app, while the developer should have access to features like easy browsing, sorting etc. I am even cosidering a switch like "User/Developer". If you are a user, you would probably like to know if there is any comment, which extends what has been said in particular paragraph. And if you're a developer, you're rather searching for open / high priority issues. So, by default, everyone is a user, and has access to comments and is able to add his own comments. In such case, user should be informed if there are any comments interesting from his point of view (like, someone decided to extend given block of text and it probably is more important and interesting to an ordinary reader). But, when you switch to developer mode, you're changing perspective. The app should help you deal with open issues. You should be able to view all the comments for selected files and sort the comments by priority, type or status, change type/priority, accept or reject a comment and so on. > * 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. Thanks, php.net is a great example of well-commented documentation. I'll make use of it. > 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. Another good point, thanks! > * 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. In Django book there's 'all comments' bookmark, so you can easily take a look at all the comments for particular page. > * 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. I am not sure that I get this point. Could you elaborate a bit more? > * 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? Good questions. I think that we should provide a few ways of dealing with this: from deleting given comments through pushing them to the bottom of the page to hiding them deeper. It should be a matter of configuration what is allowed and what's not. >> 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. In case there's a general agreement for user/developer switch I think that we should split the priorities along this line. Thanks for your comments Pauli, -- Regards, Wojtek Walczak, http://tosh.pl/gminick/ --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
