36,375
edits
Tekwiki Guidelines: Difference between revisions
no edit summary
("edit" leading to template is no longer a problem since the templates in question now include a "__NOEDITSECTION__" directive.) |
No edit summary |
||
| Line 14: | Line 14: | ||
In general, don't worry about style or formatting issues too much. We really appreciate good technical input in any form, and will help with formatting if needed. | In general, don't worry about style or formatting issues too much. We really appreciate good technical input in any form, and will help with formatting if needed. | ||
===Quotes=== | |||
If you quote a person or a document, make that clear by saying who/what is being quoted, and using <code><nowiki><blockquote>...</blockquote></nowiki></code> tags. | |||
It's fine to have text in the first person inside of an attributed quote – for example, see the quote toward the top of the [[524]] page. | |||
===Tables=== | |||
The Mediawiki software is limited in its ability to size pages and tables especially to fit different browsers. | |||
A useful way to ensure that tables you create look reasonable for most viewers is to first resize your browser window so that it just barely shows the following 7 column wide list, widely used on the [[Main Page|main page]], on a single line without reflowing: | |||
<div style="column-count:7;-moz-column-count:7;-webkit-column-count:7"> | |||
* 067-1234-01 | |||
* 067-1234-02 | |||
* 067-1234-03 | |||
* 067-1234-04 | |||
* 067-1234-05 | |||
* 067-1234-06 | |||
* 067-1234-07 | |||
</div> | |||
This will tend to give you a window that is slightly narrower than desired by popular web sites. If your table looks good at this window size, it will work for most people. | |||
===Units=== | |||
[[File:Unit buttons.png|right|thumb|450px]] | |||
We aren't rigid about imperial units versus metric, e.g., kg versus lb. Use one, or the other, or both. | |||
On Tekwiki, we use a space between the number and the unit. It's best to use a non-breaking space. | |||
:'''Pro Tip:''' The predefined unit buttons shown under the text editor make it easy to insert units beginning with a non-breaking space character, and many of the special characters like "Ω". | |||
===Attribution=== | |||
Sometimes another website has the perfect photo, or perfect document, or perfect table of data that's not available elsewhere. | |||
In those cases, it is fine to link to the external resource from a Tekwiki article. | |||
But we want Tekwiki to last for a long time, so it is good to make a local copy if possible, in case the external website (or just that resource) disappears. | |||
One way to do this is to make a copy of the resource, but to comment out the link to the local copy, and have the active link go to the external site. | |||
If the external site disappears, we can uncomment the local link and comment the external link. | |||
===Links=== | |||
'''Internal links are helpful. ''' | |||
When another instrument is mentioned in a page, make that a link in case readers want to explore that connection. | |||
==Scans== | ==Scans== | ||
| Line 41: | Line 81: | ||
It is helpful if files are named <document_part_number>.pdf. For example, 070-8123-45.pdf. | It is helpful if files are named <document_part_number>.pdf. For example, 070-8123-45.pdf. | ||
This allows us to create links to manuals we don't have yet, and the link starts working | This allows us to create links to manuals we don't have yet, and the link starts working when somebody uploads the file, named in the recommended way. | ||
when somebody uploads the file, named in the recommended way. | The document part number is usually found on the title page and/or the page footer of Tek manuals. | ||
usually found on the title page and/or the page footer of Tek manuals. | |||
When uploading a PDF document with a 070-1234-00 style document number, please add it to the [[manuals]] list whether you also reference it elsewhere or not. | When uploading a PDF document with a 070-1234-00 style document number, please add it to the [[manuals]] list whether you also reference it elsewhere or not. | ||
| Line 50: | Line 89: | ||
Too often, the remote site disappears and we end up with broken links and no way to access the document. | Too often, the remote site disappears and we end up with broken links and no way to access the document. | ||
Strongly prefer PDF files with password protection completely turned off. [http://qpdf.sourceforge.net QPDF] is useful for removing encryption and thereby also clearing the various print/copy permission flags. | Strongly prefer PDF files with password protection completely turned off. [http://qpdf.sourceforge.net QPDF] is useful for removing encryption and thereby also clearing the various print/copy permission flags. (Online alternative: https://pdf.io/unlock/) | ||
==ROM Images== | ==ROM Images== | ||
| Line 62: | Line 101: | ||
The file naming scheme we use is <tek part number>.bin. Example: 156-0660-01.bin | The file naming scheme we use is <tek part number>.bin. Example: 156-0660-01.bin | ||
==Categories== | ==Categories== | ||
| Line 111: | Line 110: | ||
If it seems appropriate to add a certain category tag to a page, do so. | If it seems appropriate to add a certain category tag to a page, do so. | ||
Also, if it seems appropriate to make a new category, do so. | Also, if it seems appropriate to make a new category, do so. | ||
:'''Pro Tip:''' The '''[https://w140.com/tekwiki/wiki/Special:CategoryTree?target=Category%3ATekWiki&mode=categories&namespaces=&title=Special%3ACategoryTree Category Tree]''' function allows you to navigate the category hierarchy with ease. | |||
Categories are usually categorized themselves, thereby creating a hierarchy of categories, or taxonomy. | Categories are usually categorized themselves, thereby creating a hierarchy of categories, or taxonomy. | ||
For example, the category "TM500 multimeter plugins" is categorized as both "Digital multimeters" and "TM500 series plugins". | Here's an example category hierarchy: | ||
: TekWiki → Technology → Test equipment → Oscilloscopes → Sampling scopes → Digital Sampling scopes → 11800 series mainframes | |||
The general convention is not to add a both a more specialized category and its parent category – e.g. a page in category ''Dual-beam CRTs'' should not have category ''Cathode ray tubes'' as well because that is the parent category of ''Dual-beam CRTs'' (logic: every dual-beam CRT is a cathode ray tube anyway). | |||
It is possible to assign multiple categories. For example, the category "TM500 multimeter plugins" is categorized as both "Digital multimeters" and "TM500 series plugins". | |||
==Talk/Discussion Pages== | ==Talk/Discussion Pages== | ||
| Line 152: | Line 158: | ||
Low noise often comes from having adequate light. | Low noise often comes from having adequate light. | ||
When photographing an instrument, it's good to also get internal photos. | |||
Avoid geometric distortion (like taking a front panel shot from above, | Avoid geometric distortion (like taking a front panel shot from above, or a close-up taken with a wide-angle lens), and trim excessive unrelated background. | ||
or a close-up taken with a wide-angle lens), and trim excessive unrelated background. | |||
Prefer photos without the in-camera flash. In-camera flashes usually result in high glare, hard shadows, and poor color rendition. | |||
Using a high f stop and indirect flash (e.g. via a white ceiling) helps put a large part of the image in focus. | Using a high f stop and indirect flash (e.g. via a white ceiling) helps put a large part of the image in focus. | ||
See e.g. https://snapshot.canon-asia.com/article/eng/5-simple-bounce-flash-photography-tips | |||
File names should be relate to the subject of the photo. Cameras generate semi-arbitrary filenames. | File names should be relate to the subject of the photo. Cameras generate semi-arbitrary filenames. | ||