Simon Paquet wrote: > > So, any suggestions for the document here?
> You are a new bug triager who has just obtained > new permissions in bugzilla.mozilla.org. Don't make such explicit, specific assumptions about the reader. He is just as likely to be a person without any permissions, maybe one who just wants to get a better idea of what they are. > Here you find information explaining I suggest using "This document explains" instead. You should avoid "here" in general. You use it too much. > It allows you to confirm bugs. It also allows your > bug reports to start in the confirmed state (NEW). Combine these last two sentences. Also, you want to start the paragraph with the main definition (what canconfirm is), not a side note (that it's the first privilege). e.g. The canconfirm privilege allows you to confirm bugs and also to start your bug reports in the confirmed state (NEW). > _Here_ NEVER link with the text "here". > Please apply as many steps listed in the guide for > confirming unconfirmed bugs or the confirming layout > bugs guide as possible before reporting a bug with > status NEW, because fewer bug triagers will look at > confirmed bugs, and a second view can be useful. This could be made easier to understand if you just stipulate that starting bugs as NEW means you've gone through the triage process already yourself. > Upgrading your permissions This section belongs under Editbugs. > After you have reported and/or confirmed a few bugs > you are probably eager to do more. This sentence is more or less useless. It could, however be tweaked to give a brief idea of when someone should be applying for editbugs. > The more powerful Editbugs privilege level gives you You vary between "privilege" and "privilege level". Pick one concept and stick with it. > the privileges of Canconfirm and also the ability > to edit most aspects of a bug. Therefore, this > privilege should be used with special care. The last sentence has the literary power of "That's nice." How about something like a "don't abuse your privileges"? > To resolve bugs is an important task for a bug triager. Fluff. Take out. > Whenever you resolve a bug CC yourself comma after bug > See this _guide_ for screening DUPLICATE bugs. Extend the link to the end of "bugs". You want the link text to stand out on its own. I should be able to scan the document, pick out the links (they stand out), and know where each one will go. > (for example bug description and/or summary are clearer, > a patch is already attached, a lot of people are already > CC'ed, etc.) You can take out the "for example" and the linking verbs (is, are). Also, I don't think a clearer summary is a good reason to give something better emphasis. A better description is important, but the summary is easy to change. So, you can recommend changing the summary to the better one. > Also bugs on websites, which are the result of bad coding > or use of proprietary technology, bugs *in* websites *that result from* bad coding or use of proprietary technology [no comma] > The decision to mark a bug WONTFIX is reserved for developers. Do you want to restrict that to the module owner/peer group? > Verifying DUPLICATEs is the easiest task, so you should start with it. start with that. > is relatively easy, if a developer no comma > Before verifying FIXED bugs, you should make sure that > the bug triager can verify them on every hardware/OS > they were reported on. I'm confused. Isn't "you" the "bug triager"? > For verifying WORKSFORME bugs there are no clear steps. There are no clear steps for verifying WORKSFORME. > At the top of every bug report ... This paragraph serves no great purpose. You can take it out. > This policy does also apply for all bugs with Target Milestones > in the past. "(Bugs with Target Milestones in the past are /not/ excepted.)" > network connectivity (ftp, http, IMAP) or HTML rendering or -> and > if a bug also exists in the Application Suite a bug -> the bug In general, if you can take a sentence or phrase out (i.e. it's not offering the reader any useful information), take it out. If the result reads awkwardly, then you're doing something else wrong and need to adjust either the wording or the sentence organization. Try imagining yourself just starting out. What would you need to know and what's just fluff? Coding ------ a) Put the heading text in the anchors. b) Don't use emphasis (<strong>) for codes. <code> is more appropriate. c) Don't use capital letters for emphasis. Use <strong class="stronger">, if you need to. d) Consider using <div class="section"> to structurally organize the document. e) Read the mozilla.org Documentation Style Guide. This is all in there. :) ~fantasai _______________________________________________ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
