Merge branch 'master' of /home/vorner/pciids

[pciids.git] / help / newitem

diff --git a/help/newitem b/help/newitem
index e073b8f1d14a5d90f85098b334a67cce44180370..4308893ffb5c2d2bbece2c731a881391bd5487e9 100644 (file)
--- a/help/newitem
+++ b/help/newitem
@@ -1,33 +1,54 @@
-Add a new item
+Adding a new item
 <p>
-If you know about an ID not present here, you can submit it.
-Browse to the item which should contain it and click <a href='$AC_URL$newitem'>add item</a> link.
+If you know about an ID which is not listed in the database, you are welcome
+to submit a new entry.
 <p>
-You need to fill in the ID and its name.
-The ID is just the last part (without parent part, for example if you have PCI device <tt>1234:5678</tt> and the vendor <tt>1234</tt> already exists, you enter only <tt>5678</tt>).
-If you know chip name, it is preferred over marketing name.
+To add it, browse to its parent entry, click on the <a href='$AC_URL$newitem'>add item</a> link
+and enter the last part of the new ID (without the parent ID) together with its name.
+For example, when you want to submit the PCI device <tt>1234:5678</tt> (vendor ID <tt>1234</tt>,
+device ID <tt>5678</tt>) and the vendor <tt>1234</tt> already exists, go to the page of
+that vendor and enter a new item with ID <tt>5678</tt> there.
 <p>
-You can add some note to the name, for example, if the ID is not really owned by the company using it.
-You can add a discussion comment to it (why you think it is correct).
-The difference between note and discussion is that note is additional information to name, while discussion is administrative.
-Also, note is sometimes distributed, while discussion isn't.
+If you want to change an existing entry, just <a href='$HELP_URL$newdiscuss'>post a discussion
+item</a> instead.
 <p>
-Both note and discussion is optional.
+You can also add a note to the name. The notes are distributed together with the ID's,
+so they should be used only in important cases (for example to draw attention to the fact
+that the ID was used by a different company due to a mistake).
 <p>
-After you submit it, it will wait approval of an admin.
-
-<h2>Approval</h2>
-<p>
-Each item is checked and approved by an admin.
-It is because not all submissions are correct.
+If you want to comment on anything, feel free to post a discussion comment. (Unlike
+the note, it is only kept for other people editing the lists, not distributed to
+users.)
 <p>
-If you want to it to get approved, please check you enter valid information into correct place (eg. not an USB ID into PCI devices, Device into its vendor).
-You should check help specific for each tree:
+After you submit the change, it will wait for approval by an admin.
+
+<h2>Rules</h2>
+<p>
+<em>There is a couple of simple rules you should obey:</em>
+<ul>
+       <li>Avoid generic names like "unknown network card", they are not
+       likely to help anybody.
+       <li>Prefer chip names over marketing names. If you know both,
+       please include the marketing name in square brackets
+       (e.g., "<tt>3c595 100BaseTX [Vortex]</tt>").
+       <li>Do not repeat the name of the vendor in the name of the device.
+       <li>Look at the names of similar devices and follow the same form.
+       <li>Verify the kind of the entry: do not submit subsystems as devices,
+       do not submit USB ID's to the PCI lists :-)
+</ul>
+<p>If you are not familar with the syntax of the ID's, please check the description:
 <ul class='navigation'>
        <li><a href='$HELP_URL$pci'>PCI devices</a>
        <li><a href='$HELP_URL$pci_class'>PCI device classes</a>
 </ul>
 
+<h2>Approval</h2>
+<p>
+All submissions are checked by the administrators for errors. The admins either approve
+the entry, or ask you to correct it or to provide more details. In cases of blatant
+abuse (spam in comments etc.), they have the power to remove the entry completely.
+<p>
+
 <h2>Notification subscription</h2>
 <p>
 If the subscribe checkbox is checked, a notification on the new item will be created for you.
@@ -35,6 +56,6 @@ For more information about notifications look at <a href='$HELP_URL$notification
 
 <h2>See also</h2>
 <p>
-Once item is submitted, it is not sealed for ever. You can <a href='$HELP_URL$newhistory'>discuss</a> existing items and suggest them new names.
+Once an item is submitted, it is not sealed for ever. You can <a href='$HELP_URL$newhistory'>discuss</a> existing items and suggest new names for them.
 <p>
-If you are interested in changes in some item (or its whole subtree), you can let the system send you <a href='$HELP_URL$notifications'>notifications</a>.
+If you are interested in changes in some item (or in its whole subtree), you can let the system send you <a href='$HELP_URL$notifications'>notifications</a>.