36,230
edits
No edit summary |
|||
(19 intermediate revisions by 4 users not shown) | |||
Line 11: | Line 11: | ||
Avoid unattributed text in the first person. | Avoid unattributed text in the first person. | ||
We have some [[article templates]] that generate headlines, infoboxes and the like. Using these | We have some [[article templates]] that generate headlines, infoboxes and the like. Using these is strongly encouraged as they populate respective [[Special:CargoTables|database tables]] and make it easier to see what information is missing. | ||
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 32: | Line 72: | ||
Recommendation: Turn off all processing except for OCR. | Recommendation: Turn off all processing except for OCR. | ||
Always keep the raw scan in case it needs to be reprocessed for whatever reason. | Always keep the raw scan in case it needs to be reprocessed for whatever reason. | ||
Maybe in twenty years, the automatic enhancement software will be reliable. | Maybe in twenty years, the automatic enhancement software will be reliable. | ||
The eventual goal is for all PDFs on Tekwiki to be text-searchable. | |||
If a PDF isn't already text-searchable, add the "Needs OCR" category tag to the file page. | |||
It is fine to upload scans that other people made for free distribution. | It is fine to upload scans that other people made for free distribution. | ||
Line 38: | 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 46: | Line 88: | ||
Rather than linking to a document on a remote site, prefer to upload of copy of the document to Tekwiki. | Rather than linking to a document on a remote site, prefer to upload of copy of the document to Tekwiki. | ||
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. (Online alternative: https://pdf.io/unlock/) | |||
==ROM Images== | ==ROM Images== | ||
Tekwiki hosts a collection of [[ROM images]] | Tekwiki hosts a collection of [[ROM images]]. | ||
ROM images should be uploaded in plain binary format. S-record files can be converted beforehand using GNU binutils: | |||
< | <tt> | ||
objcopy -I srec -O binary rom.hex rom.bin | |||
</tt> | |||
</ | |||
The file naming scheme we use is <tek part number>.bin. Example: 156-0660-01.bin | |||
==Categories== | ==Categories== | ||
Line 98: | 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 139: | 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, or a close-up taken with a wide-angle lens), and trim excessive unrelated background. | 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. | ||
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. | |||
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. | |||
Those should be replaced with more meaningful names before the files are uploaded. | |||
The filename extension should be lowercase. | |||
For example. rename "IMG_143721.JPG" to "tek_647a_hv_transformer.jpg". | |||
When uploading a file, the name may get changed slightly by the wiki system. | |||
The text after the "File:" on the upload page (not the URL bar in the browser) | |||
is the name you should use when referring to the files. | |||
Mostly, Tekwiki refers to images inside of gallery blocks. | |||
When in doubt, look at how the markup is done on other pages. | |||
===Commented examples=== | ===Commented examples=== | ||
Line 173: | Line 204: | ||
</gallery> | </gallery> | ||
==See Also== | |||
* [[Tasks]] | |||
[[Category:TekWiki]] | [[Category:TekWiki]] |