Protospace Wiki:Adding new tools: Difference between revisions

Protospace Wiki:Adding new tools (view source)

Revision as of 06:54, 20 November 2021

12,910 bytes added , 20 November 2021

revamped page to flesh out the process and to make it easier to (understand how to) follow the process

Ian.oliver

Administrators

327

edits

@@ Line 1: / Line 1: @@
-==General==
+If a tool has been donated, semi-permanently loaned, or brought into the space for a specific short-term, it is encouraged to add the tool to the "[[tools we have]]" gallery page. This will help avoid damage due to other members being uninformed about the tool's operation, maintenance, ownership, etc. Follow this procedure to achieve that.
-If a tool has been donated, semi-permanently loaned, or brought into the space for a specific short-term, it is encouraged to add the tool to the [[Tools We Have]] page. This will help prevent people from tampering, moving, modifying, or improperly using them. Follow this procedure.
 ==Preparing to add a tool==
-Each tool is assigned a Wiki ID.  The ID numbers are assigned in a chronological order. Don't leave gaps in the sequence.
+* Gather information on the tool. Try to get as much of the following information as you can, but don't worry about missing information as long as its absence won't keep anyone from figuring out which physical tool at Protospace corresponds to which gallery entry or page on the wiki.
+* Decide whether you want to add 1) just an entry in the [[tools we have|tools gallery]] or 2) a full page about the tool. The latter is generally preferable because it's more useful to people looking for info on the tool in the future, and because it allows the assignment of a Wiki ID number for the tool. Even if you feel like you only have enough information for a gallery entry, you may still (and are encouraged to) make a full page, because this make it easier for others to fill in that info later.
-The first step when adding a tool is to chose the next available ID number, which will be used when assigning the picture name, as well as creating a redirect page for short URLs.
+* Take a photo of the tool.
+** Try to take it in good lighting.
-To view the next available Wiki ID (and the ID numbers that have been assigned), click <b>[[0|here]]</b>  (Note: verify the number before proceeding.  Make sure that the number listed is in fact available.)
+** If you can, make the background as uncluttered as possible. (Suggestions: Put the tool against a blank wall or on a clean table. Put a piece of cardboard or plywood behind the tool. Edit the photo to blur the background/surroundings.)
+** Crop it if necessary to avoid excessive space around the tool at the edges of the photo.
-Remember to update that page if you use the number that is listed.
+* '''Consider whether those who work on the wiki after you will be able to easily tell which physical item in Protospace is represented by what you're about to add.''' If the answer is no, consider what additional info you could include (or how else you could distinguish the tool, such as by adding a label to it) to help with this. Adding information that refers to a tool that others can't positively identify in the physical world is probably worse than not adding the tool to the wiki at all. If in doubt, ask on the forum (or an appropriate talk page on the wiki that may exist in the future).
-==Adding the Picture==
-* It is easiest to add the picture first. While encouraged, it's not necessary, a single text line with basic info is acceptable instead of an individual tool page.
-* When taking the picture, try to take it in good lighting in a blank (or cardboard/plywood) background. Then crop it accordingly.
+==Option 1: Adding a tool as just an entry in the tools gallery==
-**Add a picture file, click the [[Special:Upload]] link on the left menu (or the one I just linked).
-**The picture's filename should use the format ''ID_number_of_tool.file_extension''. example: [[:File:106.jpg|106.jpg]]
-**Give the picture a short description and upload it.
-* Copy/remember the filename or leave that tab open, you'll need it right away.
+This option will result in an entry for the tool on the [[tools we have]] page. It will consist of a photo (which can be clicked to enlarge) and whatever description you type in. Don't worry—it can be upgraded to a tool page later.
-Then you're ready to create a tool page.
+* Advantages: quick and easy
+* Disadvantages: not as informative; the tool may not be assigned a Wiki ID; info about the tool cannot be easily linked to from elsewhere on the wiki/forum or from a label on the tool
-==Creating a Tool Page==
+Procedure:
-* Edit the [[Tools We Have]] page and insert a line to the appropriate alphabetical place. Copy and paste this, change it for your specific info:
+# Upload the photo of the tool. '''DO NOT use a number as the filename.''' (It can be moved to a number later if a Wiki ID is assigned to the tool.) Try to use a short and descriptive name of the tool, such as its make and model, its color, etc., but the exact name is unimportant for now, as long as you can copy and paste it. Once the upload is done, either copy the filename from the top of the page, or leave the tab open so you can do that when you reach step 3.
-**<nowiki>File:999.jpg|[[Tool Name ID:999]]</nowiki>
+# Decide on a name for the wiki to refer to the tool by. At this point (before the page is created) it doesn't matter as much, but try to follow the format: <code>[tool type], [distinguishing characteristics separated by commas] ([make/model])</code> (with each part but the first being included only if it makes sense). If the tool was made by a member and therefore has no make/model, use the member's name in possessive form.
+#: Examples:
+#:* Laser cutter, large (Rabbit Laser RL-80-1290)
+#:* Counter (Fluke 1910A Multi-Counter)
+#:* Function generator (John's)
+#:* Power supply, bench, 2-channel (TENMA 72-7245)
+#:* Vise, wood (Travis's)
+#:* Magnifier lamp, large, without lid
+#:* Forge, propane (Jim's)
+# Edit the appropriate section of the [[tools we have]] gallery to insert an entry. Insert it in the appropriate place in the section according to where the name you chose in step 2 fits in alphabetical order.
+#* If editing in source mode, copy and paste the code below, or follow the format of the entries already there.
+#*: <pre>File:FILENAME                           |TOOLDESCRIPTION</pre>
+#* If editing in visual mode, double-click the gallery in the appropriate section (or click once to select it and then click the "Edit" button that appears), then click "+ Add new image" at the bottom-left of the popup window. In the search box, type in the filename of the image, including the filename extension. When the image appears, click it. It will join the others in the column on the left; drag it to the appropriate alphabetical position. Don't close the popup window yet.
+# Fill in the info:
+#* If editing in source mode, replace <code>FILENAME</code> with the name of the image you uploaded, such as <code>File:Red hacksaw.jpg</code>, and replace <code>TOOLDESCRIPTION</code> with the name you decided on in step 2, followed by any other info you think is important to include. Be careful to not delete the pipe (<code>|</code>) before <code>TOOLDESCRIPTION</code>, and make sure there are no spaces immediately after the pipe.
+#* If editing in visual mode, click the link button (with the chain icon) at the top of the caption field below the image on the right side of the popup window. Start typing the title of the page you created, and click it when it appears in the suggestions. Now click the blue "Apply changes" button at the top-right of the popup window.
+# If editing in source mode, click the "Show preview" button at the bottom of the editor to check that your addition appears correctly. (In visual mode, the editor itself serves as the preview.) If not, try to fix it so it does. If you can't, proceed anyway, and somebody else will probably fix it soon.
+# Click the "Save changes" button (at the bottom in source mode or the top-right in visual mode) to publish your addition, preferably with an edit summary saying which tool you added.
-* Replace 999 with your tool's ID
+==Option 2: Adding a tool page==
-* It's easy to figure out, just copy the ones above or below it in the list except for the changes.
-* Preview, leave a comment on what you did, and then click Save Page.
-The new tool page has now been created and linked in the Tools We Have document.
+This option will result in a page about the tool, linked from the tools gallery. Clicking on the picture in the tools gallery will open the tool's page instead of enlarging the picture (though you can still enlarge the picture by clicking on it where it appears in the tool's own page).
-==Adding Content to the Tool Page==
+* Advantages: more informative; the tool may be assigned a Wiki ID; info about the tool can be easily linked to from elsewhere on the wiki/forum and from a label on the tool<br/>
+* Disadvantages: more work on your part
-* Scroll until you find your tool in the list. The thumbnail should show up and the text below should be the red toolname page.
+Procedure:
-* Click the red toolname page.
+# Decide on a name for the wiki to refer to the tool by. Try to follow the format: <code>[tool type], [distinguishing characteristics separated by commas] ([make/model])</code> (with each part but the first being included only if it makes sense). If the tool was made by a member and therefore has no make/model, use the member's name in possessive form. (Don't worry too much about getting it exactly right—anybody can fix it later by moving the page and updating any redirects.) '''Don't add an ID number at the end yet.'''
+#: Examples:
+#:* Laser cutter, large (Rabbit Laser RL-80-1290)
+#:* Counter (Fluke 1910A Multi-Counter)
+#:* Function generator (John's)
+#:* Power supply, bench, 2-channel (TENMA 72-7245)
+#:* Vise, wood (Travis's)
+#:* Magnifier lamp, large, without lid
+#:* Forge, propane (Jim's)
+# Enter that name in the search box at the top right (in the default skin (Vector) on desktop). You should see just a single suggestion in the dropdown, which says "containing... [what you entered]". Click that or press Enter/Return (or do the latter even if you don't see that suggestion). You should arrive on a search results page where there's a line below the search box and options that says "Create the page "[what you entered]" on this wiki!". Click the redlink in the middle of that line. Now you will arrive at an editor with what you entered set as the page's title.
+# Add the template to the page:
+#* If editing in source mode, copy and paste the following code into the editor:
+#*:<!-- credit for the method of putting multi-line <pre> code inside a list: https://stackoverflow.com/a/8390173 --><pre>
+#*::{{Equipment page
+#*::| toolname =
+#*::| model =
+#*::| serial =
+#*::| owner =
+#*::| loanstatus =
+#*::| arrived =
+#*::| location =
+#*::| status =
+#*::| permission =
+#*::| certification =
+#*::| photo =
+#*::| caption =
+#*::| id =
+#*::}}</pre>
+#* If editing in visual mode, choose "Template" from the "Insert" menu at the top of the editor. A popup window will appear. Start typing "equipment page" in the field and click it once it's suggested.
+# Fill in the template. '''Leave <code>photo</code>, <code>caption</code>, and <code>id</code> blank for now.''' With the other fields, enter a question mark or leave it blank if you don't know that information. <code>toolname</code> is not supposed to be in the same format as the page title (what you decided on in step 1); instead, it should be more of a natural-sounding but still detailed name, such as "Tormach PCNC 1100 CNC mill" or "red 12" hacksaw". For help with the other fields, see the descriptions at [[Template:Equipment page]].
+#* If editing in source mode, add the appropriate information on each line, after the equals sign. (If you copied and pasted from above, there should already be a space after each equals sign. Spaces are optional on both sides, but they improve code readability.
+#* If editing in visual mode: The template isn't set up for convenient visual editing yet, so you'll have to manually enter the full name of each field you want to use in the "Field name" search box and click it as an unknown field below that, then fill it in above. When you're done, click the blue "Insert" button at the top right of the popup window.
+# Add any other information you want to below the template. It's commonly useful to include sections for specifications, usage instructions, repair tips, etc. (Reminder: the code for a section heading is <code>==Section title==</code>, with more equals signs for further levels.) If you don't have this information now, it can of course be added later.
+# Add all appropriate tool categories. If you forget any of these, don't worry, because you can come back and fix it later, or someone else can. The current tool categories can be found listed in the "Subcategories" section of [[:Category:Tools]]—blue triangles there are clickable to expand subcategories. You can also add categories that don't exist, and they'll appear at [[Special:WantedCategories]] so we know they're wanted.
+#* In source editing, this is done by simply adding links to the categories (e.g., <code><nowiki>[[Category:Showcase tools]]</nowiki></code>), usually at the very bottom of the page's code. They won't appear as links once you save the page. When previewing, they'll appear at the very bottom, below the editor even if you have the preview set to appear above the editor.
+#* In visual editing, there is a category tool accessible from the hamburger menu at the top right, just to the left of the editing mode menu.
+# Preview and save the page:
+#* If editing in source mode:
+#*# Click the "Show preview" button at the bottom of the editor to check that the page appears correctly. You should see an infobox on the right side of the preview, with the info you entered. If not, try to fix it so you do. If you don't, proceed anyway, and somebody else will probably fix it soon.
+#*# Click the blue "Save page" button at the bottom of the editor to publish your addition.
+#* If editing in visual mode:
+#*# The editor itself serves as the preview. Look at what appears after closing any popup windows. You should see an infobox on the right side of the preview, with the info you entered. If not, try to fix it so you do. If you don't, proceed anyway, and somebody else will probably fix it soon.
+#*# Click the blue "Save page" button at the top-right of the editor to publish your addition.
+# (optional) If you want to assign a Wiki ID number today, do that now according to [[0#I want to assign a Wiki ID number to a tool or other item|the instructions for that]].
+# Upload a photo. If you've assigned a Wiki ID number, upload it with that number as the filename, such as <code>512.jpg</code>. If you haven't, try to use a short and descriptive name of the tool, such as its make and model, its color, etc., but the exact name is unimportant for now, as long as you can copy and paste it. Once the upload is done, either copy/remember the filename from the top of the page, or leave the tab open so you can do that in the upcoming steps.
+# Edit the tool page you created to add the photo. First, copy and paste the following code into the <code>photo</code> field of the equipment page template: <code><nowiki>[[File:FILENAME|350px|thumb|right|]]</nowiki></code>. Then replace FILENAME with the filename, such as <code><nowiki>[[File:512.jpg|350px|thumb|right|]]</nowiki></code> or <code><nowiki>[[File:Red hacksaw.jpg|350px|thumb|right|]]</nowiki></code>.
+# Preview and save the page again, preferably with an edit summary saying you added a photo.
+# Go to the [[tools we have]] gallery, find the appropriate section, and click the edit button on that section so you can insert an entry. Find the appropriate place in the section according to where the name you chose in step 1 fits in alphabetical order.
+#* If editing in source mode, copy and paste the following code:
+#*: <pre>File:FILENAME        |link=TOOLDESCRIPTION            |[[TOOLDESCRIPTION]]</pre>
+#* If editing in visual mode, double-click the gallery in the appropriate section (or click once to select it and then click the "Edit" button that appears), then click "+ Add new image" at the bottom-left of the popup window. In the search box, type in the filename of the image, including the filename extension. When the image appears, click it. It will join the others in the column on the left; drag it to the appropriate alphabetical position. Don't close the popup window yet.
+# Fill in the info:
+#* If editing in source mode, replace <code>FILENAME</code> with the name of the image you uploaded, such as <code>File:512.jpg</code> or <code>File:Red hacksaw.jpg</code>, and replace <code>TOOLDESCRIPTION</code> (both times, identically) with the title of the page you created, such as <code>link=Hacksaw, 12", red</code> and <code><nowiki>[[Hacksaw, 12", red]]</nowiki></code> or <code>link=Hacksaw, 12", red ID:512</code> and <code><nowiki>[[Hacksaw, 12", red ID:512]]</nowiki></code>. Be careful to not delete the pipes (<code>|</code>), and make sure there are no spaces between the second pipe and the beginning of the link code (<code><nowiki>[[</nowiki></code>).
+#* If editing in visual mode, click the link button (with the chain icon) at the top of the caption field below the image on the right side of the popup window. Start typing the title of the page you created, and click it when it appears in the suggestions. Now click the blue "Apply changes" button at the top-right of the popup window. Editing visually, you can't set the <code>link=</code> parameter; somebody else might do that, or you can add it yourself by editing again in source mode.
+# If editing in source mode, click the "Show preview" button at the bottom of the editor to check that your addition appears correctly. (In visual mode, the editor itself serves as the preview.) If not, try to fix it so it does. If you can't, proceed anyway, and somebody else will probably fix it soon.
+# Click the "Save changes" (at the bottom in source mode or the top-right in visual mode) button to publish your addition, preferably with an edit summary saying which tool you added.
-* There is a [[Template:Equipment page|template]] made (you can click that link to see more). Don't edit the Template. Use it. Copy and paste the following code into the edit box of the new tool page:
+==Upgrading a tool from just a gallery entry (option 1) to a page (option 2)==
-<pre><nowiki>
+:''Prerequisite: a gallery entry, created as described under 'Option 1' (above)''
-{{Equipment page
-| toolname =
-| model =
-| serial =
-| owner =
-| loanstatus =
-| arrived =
-| location =
-| status =
-| permission =
-| certification =
-| itemphoto = [[File:.jpg|350px|thumb|right|]]
-}}
-==Specs==
-</nowiki></pre>
-* Then fill in the missing info. Anything not applicable write N/A, anything unknown leave ?? so someone in the future can know it needs filing in.
+This upgrade procedure will result in a page about the tool, linked from the tools gallery. Clicking on the picture in the tools gallery will open the tool's page instead of enlarging the picture (though you can still enlarge the picture by clicking on it where it appears in the tool's own page).
-** If uncertain, look at other tool pages to get an idea, or read the [[Template:Equipment page|template]] page.
-** Don't forget to insert the picture filename again (last line, between <nowiki>[[File:]]</nowiki> and <nowiki>.jpg|</nowiki> ).
-** Add in tool specs and explain briefly what the tool is and what it's used for.
-* Add sections below if relevant. Often "<nowiki>==Usage Notes==</nowiki>", "<nowiki>==Repair Notes==</nowiki>", are helpful.
+Procedure:
-* Preview and see if it looks right. Save page.
+''[not written yet; you can probably figure it out if you need to]''
-==Seeing Your Results==
+==Assigning a Wiki ID to a tool that doesn't have one==
+:''Prerequisite: an equipment page, created as described under 'Option 2' or 'Upgrading a tool from just a gallery entry (option 1) to a page (option 2)' (above)'''
-* Click to return to Tools We Have, your red link should now be blue (or purple), and clicking it should bring you back to the tool page.
+Procedure:
-* If this doesn't work, or you screwed up, ask someone for help.
+''[not written yet; you can probably figure it out if you need to]''