Tekwiki Guidelines: Difference between revisions

From TekWiki
Jump to navigation Jump to search
No edit summary
(41 intermediate revisions by 4 users not shown)
Line 1: Line 1:
This page provides guidelines on Tekwiki content.
This page provides '''guidelines on Tekwiki content'''.
These are things to consider, not rigid rules.
These are things to consider, '''not rigid rules'''.


Something is usually better than nothing.
*Something is usually better than nothing.
Perfectionism is harmful.
*Perfectionism is harmful.
It's ok to click "Save changes" when things aren't perfect.
*It's ok to click "Save changes" when things aren't perfect.
We can improve things later.
*We can improve things later.


==Text==
==Text==
Text should be in the style of an encyclopedia.
'''Text should be in the style of an encyclopedia. '''
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 makes it easy to have consistently styled articles, but they are optional to use.
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.


==Scans==
==Scans==
Favor any scan over no scan.  
'''Favor any scan over no scan. '''
The presence of free scans of manuals and other documentation is hugely important.
The presence of free scans of manuals and other documentation is hugely important.
In many cases the availability of a free scan makes the difference between an instrument being put in the trash versus being restored.
In many cases the availability of a free scan makes the difference between an instrument being put in the trash versus being restored.


Favor high quality over small file size.  
'''Favor high quality over small file size. '''
What seems like a big file today will not seem so big in ten years.  
What seems like a big file today will not seem so big in ten years.  
Favor one-up (one document page per PDF page).
When scanning a document, best quality is obtained by removing the binding
and scanning the pages flat.


Beware of software that claims to provide automatic image enhancement for scans.  
Beware of software that claims to provide automatic image enhancement for scans.  
Line 23: Line 32:
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.  
Don't upload scans from companies like Artek, where the scan was done to make money.
Don't upload scans from companies like Artek, where the scan was done to make money.


==Photos==
It is helpful if files are named <document_part_number>.pdf. For example, 070-8123-45.pdf.
Any photo is better than no photo.
This allows us to create links to manuals we don't have yet, and the link starts working
Prefer high-resolution, in-focus photos.
when somebody uploads the file, named in the recommended way.  The document part number is
Don't use photos from other websites if you think it will upset the owner of the photo.
usually found on the title  page and/or the page footer of Tek manuals.
Prefer diffused lighting (no hard shadows), natural color balance, and good color rendition.  
 
Good color rendition often comes from having minimal glare, which often comes from diffused lighting.  
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.
Prefer photos with low noise (without artificial denoising).  
 
Low noise often comes from having adequate light.  
Rather than linking to a document on a remote site, prefer to upload of copy of the document to Tekwiki.
Prefer photos without the in-camera flash.
Too often, the remote site disappears and we end up with broken links and no way to access the document.
In-camera flashes usually result in high glare, hard shadows, and poor color rendition.  
 
When photographing an instrument, it's good to also get internal photos.  
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.
 
==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


==Quotes==
==Quotes==
If you quote a person or a document, make that clear by saying who/what is being quoted, and using blockquote tags.  
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.  
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==
==Units==
On Tekwiki, we use a space between the number and the unit.  
On Tekwiki, we use a space between the number and the unit. It's best to use a non-breaking space.
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 "Ω".
 
We aren't rigid about imperial units versus metric, e.g., kg versus lb.  
We aren't rigid about imperial units versus metric, e.g., kg versus lb.  
Use one, or the other, or both.
Use one, or the other, or both.
Line 58: Line 100:


==Links==
==Links==
Internal links are helpful.  
'''Internal links are helpful. '''
When another instrument is mentioned in a page, make that a link in case readers want to explore that connection.
When another instrument is mentioned in a page, make that a link in case readers want to explore that connection.
==Caveats and Quirks==
Beware of the "edit" links next to section headings.<br>
[[File:Template section heading edit link.png]]<br>
These edit links sometimes take you to a page where you are editing the template, not the Tekwiki article.
If you end up in an edit window titled something like "Editing Template:MissingSpecs (section)", hit the back button or cancel.
The most reliable and least confusing thing is to use the edit link at the top of the page, not the edit links next to the section headings.


==Categories==
==Categories==
We have defined a number of categories.
We have defined a number of categories.
Pages are added to a category by putting a Category: tag in the page, typically at the bottom.
Pages are added to a category by putting a <code><nowiki>[[Category:...]]</nowiki></code> tag in the page, typically at the bottom.
See, for example, the bottom of the [[82|Type 82]] page.
See, for example, the bottom of the [[82|Type 82]] page.
This allows us to have an autogenerated page that lists all items in a category.
 
This allows us to have an auto-generated page that lists all items in a category.
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.
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".


==Talk/Discussion Pages==
==Talk/Discussion Pages==
Line 74: Line 127:
Tekwiki administrators monitor those pages and will respond to questions. For example, if you want to  
Tekwiki administrators monitor those pages and will respond to questions. For example, if you want to  
start a new category but aren't sure, feel free to edit the Talk/Discussion page.
start a new category but aren't sure, feel free to edit the Talk/Discussion page.
Please sign your contributions on discussion pages at the end of your text - you can simply type four tildes (<code><nowiki>~~~~</nowiki></code>) to do so.
Using colons (<code><nowiki>: your reply</nowiki></code>, <code><nowiki>:: reply to your reply</nowiki></code>) helps making the discussions more readable.
==Repair Reports - "/Repairs" Pages==
Reports of individual repairs should go on a "/Repairs" sub-page under the main article for that instrument, e.g. [[585/Repairs]]. 
A description of symptoms, causes identified and solutions implemented is most welcome, whether in bullet-list or narrative style.
Photos of the specific problem or solution will help others in their work!
The link to the repair page will be displayed in a tab on top of each article, next to the "Discussion" tab.
Information about general known repair issues such as components that are prone to failure can go into a section (e.g. "Common Problems") in the main article.
It is quite OK to have both a Common Problems section and a Repairs article [[7CT1N|for the same instrument]].
Please categorize individual repair pages using <code><nowiki>[[Category:Instrument repair reports]]</nowiki></code>.


==Collaboration==
==Collaboration==
Feel free to improve text added by other people.
'''Feel free to improve text added by other people.'''
If something is confusing, make it clear.
If something is confusing, make it clear.
If you're unsure, raise the question on the Talk/Discussion page.
If you're unsure, raise the question on the Talk/Discussion page.
==Photos==
'''Any photo is better than no photo.'''
Prefer high-resolution, in-focus photos.
Don't use photos from other websites if you think it will upset the owner of the photo.
Prefer diffused lighting (no hard shadows), natural color balance, and good color rendition.
Good color rendition often comes from having minimal glare, which often comes from diffused lighting.
Prefer photos with low noise (without artificial denoising).
Low noise often comes from having adequate light.
Prefer photos without the in-camera flash.
In-camera flashes usually result in high glare, hard shadows, and poor color rendition.
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.
When photographing an instrument, it's good to also get internal photos.
Using a high f stop and indirect flash (e.g. via a white ceiling) helps put a large part of the image in focus.
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===
<gallery>
Tek_524_trace.jpg|Hard shadows are distracting
Tek_524ad_front.jpg|Same subject, but without hard shadows
6r1a_front.JPG|Good photo, taken outside on a cloudy day
Tek_rm547.jpg|Hard shadows, but still a useful photo
Tek 511a 4.JPG|Low resolution image
Tek_1L60_from_fiche.jpg|Low quality image taken from documentation, much better than nothing
Timkoeth_519_TWK_1379.jpg|Beautiful CRT trace photo of a [[519]].
Tek_945_front7c.jpg|Good straight-on scope photo using two flashes: one bouncing off the ceiling, one passing through a white umbrella.
Tek_7a42_fr4.jpg|Good photo of traces and readout on 7000-series scope
Tek_11a33_rearleft.jpg|Good photo of the inside of an [[11A33]]. Plenty of light, but not too much glare. Colors and textures are realistic.
Tek-7623A.jpg|Good CRT traces and a good picture of the front panel in one photo. Rare.
Tek_11a33_inputrelay.jpg|Macro closeups can be interesting, particularly when they illustrate something important.
Tek_1l5_front.JPG|This image suffers from nonuniform illumination.
Type_m_front.jpg|Hard shadows from light coming from below. It seems unnatural.
Tek_1a7_front.jpg|Good color rendition. Red looks red.
Tek_type_s.jpg|Low resolution and bad color balance. The plug-in looks green.
Tek_3a74_front.jpg|Bad color balance. The plug-in looks pink.
Tek_type_mc_left.jpg|Photo using a flashlight as a light source. Nonuniform illumination and hard shadows, but decent color rendition, decent focus, and not too noisy. Much better than nothing.
</gallery>
It is difficult to get a good photo of an oscilloscope showing its trace.
<gallery>
Tek 547 trace two sine.jpg|It is common for photos of scope traces to show artifacts that are normally not seen.
</gallery>
==See Also==
* [[Tasks]]
[[Category:TekWiki]]

Revision as of 16:48, 2 September 2019

This page provides guidelines on Tekwiki content. These are things to consider, not rigid rules.

  • Something is usually better than nothing.
  • Perfectionism is harmful.
  • It's ok to click "Save changes" when things aren't perfect.
  • We can improve things later.

Text

Text should be in the style of an encyclopedia. Avoid unattributed text in the first person.

We have some article templates that generate headlines, infoboxes and the like. Using these makes it easy to have consistently styled articles, but they are optional to use.

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.

Scans

Favor any scan over no scan. The presence of free scans of manuals and other documentation is hugely important. In many cases the availability of a free scan makes the difference between an instrument being put in the trash versus being restored.

Favor high quality over small file size. What seems like a big file today will not seem so big in ten years.

Favor one-up (one document page per PDF page).

When scanning a document, best quality is obtained by removing the binding and scanning the pages flat.

Beware of software that claims to provide automatic image enhancement for scans. Automatic enhancement often corrupts the scan in ways that are hard to notice until later. Recommendation: Turn off all processing except for OCR. 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.

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. Don't upload scans from companies like Artek, where the scan was done to make money.

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 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.

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.

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.

Strongly prefer PDF files with password protection completely turned off. QPDF is useful for removing encryption and thereby also clearing the various print/copy permission flags.

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:

objcopy -I srec -O binary rom.hex rom.bin

The file naming scheme we use is <tek part number>.bin. Example: 156-0660-01.bin

Quotes

If you quote a person or a document, make that clear by saying who/what is being quoted, and using <blockquote>...</blockquote> 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, on a single line without reflowing:

  • 067-1234-01
  • 067-1234-02
  • 067-1234-03
  • 067-1234-04
  • 067-1234-05
  • 067-1234-06
  • 067-1234-07

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

On Tekwiki, we use a space between the number and the unit. It's best to use a non-breaking space. 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 "Ω".

We aren't rigid about imperial units versus metric, e.g., kg versus lb. Use one, or the other, or both.

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.

Caveats and Quirks

Beware of the "edit" links next to section headings.

These edit links sometimes take you to a page where you are editing the template, not the Tekwiki article. If you end up in an edit window titled something like "Editing Template:MissingSpecs (section)", hit the back button or cancel. The most reliable and least confusing thing is to use the edit link at the top of the page, not the edit links next to the section headings.

Categories

We have defined a number of categories. Pages are added to a category by putting a [[Category:...]] tag in the page, typically at the bottom. See, for example, the bottom of the Type 82 page.

This allows us to have an auto-generated page that lists all items in a category. 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.

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".

Talk/Discussion Pages

If you have any doubt about a change that you want to make, or a change that somebody else made, feel free to edit the associated Talk/Discussion page (the "Discussion" link at the upper left of each page). Tekwiki administrators monitor those pages and will respond to questions. For example, if you want to start a new category but aren't sure, feel free to edit the Talk/Discussion page.

Please sign your contributions on discussion pages at the end of your text - you can simply type four tildes (~~~~) to do so. Using colons (: your reply, :: reply to your reply) helps making the discussions more readable.

Repair Reports - "/Repairs" Pages

Reports of individual repairs should go on a "/Repairs" sub-page under the main article for that instrument, e.g. 585/Repairs.

A description of symptoms, causes identified and solutions implemented is most welcome, whether in bullet-list or narrative style. Photos of the specific problem or solution will help others in their work!

The link to the repair page will be displayed in a tab on top of each article, next to the "Discussion" tab.

Information about general known repair issues such as components that are prone to failure can go into a section (e.g. "Common Problems") in the main article. It is quite OK to have both a Common Problems section and a Repairs article for the same instrument.

Please categorize individual repair pages using [[Category:Instrument repair reports]].

Collaboration

Feel free to improve text added by other people. If something is confusing, make it clear. If you're unsure, raise the question on the Talk/Discussion page.

Photos

Any photo is better than no photo. Prefer high-resolution, in-focus photos.

Don't use photos from other websites if you think it will upset the owner of the photo. Prefer diffused lighting (no hard shadows), natural color balance, and good color rendition. Good color rendition often comes from having minimal glare, which often comes from diffused lighting. Prefer photos with low noise (without artificial denoising). Low noise often comes from having adequate light.

Prefer photos without the in-camera flash. In-camera flashes usually result in high glare, hard shadows, and poor color rendition.

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.

When photographing an instrument, it's good to also get internal photos. Using a high f stop and indirect flash (e.g. via a white ceiling) helps put a large part of the image in focus.

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

It is difficult to get a good photo of an oscilloscope showing its trace.

See Also