TekWiki

Tekwiki Guidelines: Difference between revisions

Page Discussion Repairs

Tekwiki Guidelines (view source)

Revision as of 02:57, 28 April 2024

3,669 bytes added ,  28 April
→‎Photos
No edit summary
 
(18 intermediate revisions by 3 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.
* Collaborate freely - '''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.
* We encourage helpful comments in the change summary – especially when it's not clear why a change was made. :-)


==Text==
 
=Page 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.
Line 15: Line 17:
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===
===Capitalization===
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.  
In general we are aligning with [[wikipedia:Wikipedia:Naming_conventions_(capitalization)|relevant conventions in Wikipedia]]. 
Inter alia, we don't capitalize the second or subsequent words in an article title, unless the title is a [[wikipedia:proper name|proper name]]. 
 
There are several places where text entered into an article template is both entered into a database, and displayed in a headline - for example, the "summary=" or "description=" arguments to various article templates.
The text in these should not be capitalized - it will be automatically capitalized in the headline display.


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.
Again, don't worry about style too much – we need your technical inputs first and foremost, the admins and regulars will help with formatting and style.


===Tables===
===Tables===
Line 41: Line 47:
On Tekwiki, we use a space between the number and the unit. It's best to use a non-breaking space.
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 "Ω".
:'''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 "Ω".
===Categories===
We have defined a number of categories.
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.
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.
Here's an example category hierarchy:
: TekWiki → Technology → Test equipment → Oscilloscopes → Sampling scopes‎ → Digital Sampling scopes‎ → 11800 series mainframes‎
:'''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.
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===
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 (<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.
It's a good idea to keep an eye on the "[[Special:Recentchanges|Recent changes]]" page so you can see the changes others are making to the wiki.
===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>.
===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.


===Attribution===
===Attribution===
Line 55: Line 108:
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.


==Scans==
To link to pages in the (English) Wikipedia, you can use the form <code><nowiki>[[wikipedia:Article name|displayed text]]</nowiki></code>, likewise to link to pages in our sister project, use [[grwiki:Main Page|GRWiki]], <code><nowiki>[[grwiki:Article name|displayed text]]</nowiki></code>.
 
=Document 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.
Line 65: Line 120:
Favor one-up (one document page per PDF page).
Favor one-up (one document page per PDF page).


When scanning a document, best quality is obtained by removing the binding
When scanning a document, best quality is obtained by removing the binding and scanning the pages flat.
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.  
Automatic enhancement often corrupts the scan in ways that are hard to notice until later.  
Automatic enhancement often corrupts the scan in ways that are hard to notice until later. <br />
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.
Line 80: Line 134:
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.


It is helpful if files are named <document_part_number>.pdf. For example, 070-8123-45.pdf.
For Tektronix manuals, our convention is to name files according to the Tek manual part number, <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.
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.
The document part number is usually found on the title  page and/or the page footer of Tek manuals.
Line 89: Line 143:
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/)
Strongly prefer PDF files with password protection completely turned off.
[https://qpdf.sourceforge.net QPDF] is useful for removing encryption and thereby also clearing the various print/copy permission flags.
A useful online alternative is https://pdf.io/unlock/


==ROM Images==
=Photos=
Tekwiki hosts a collection of [[ROM images]].  
'''Any photo is better than no photo.'''
Prefer high-resolution, in-focus photos.  When photographing an instrument, it's good to also get internal photos.  


ROM images should be uploaded in plain binary format. S-record files can be converted beforehand using GNU binutils:
Don't use photos from other websites if you think it will upset the owner of the photo.
 
<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
===Photo files in TekWiki===
File names should be related to the subject of the photo.  


==Categories==
Cameras generate semi-arbitrary filenames. Those should be replaced with more meaningful names before the files are uploaded.  
We have defined a number of categories.
The filename extension should be lowercase.  
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.


This allows us to have an auto-generated page that lists all items in a category.
For example, rename "IMG_143721.JPG" to "tek_647a_hv_transformer.jpg".
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.


:'''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.
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.
Categories are usually categorized themselves, thereby creating a hierarchy of categories, or taxonomy.
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==
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 (<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.  
Mostly, Tekwiki refers to images inside of gallery blocks.  When in doubt, look at how the markup is done on other pages.
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.
===Taking your own photos===
Prefer photos with low noise (without artificial denoising). High noise often comes from having inadequate light and therefore needing high ISO.  


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.  
'''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. Cropping very tight can look distractingly unnatural. Often it is better to leave a little bit of natural "breathing room" around the object being photographed. Shallow depth of field can be used to put the background out of focus so it is less distracting but still natural looking. Front panels look better shot from a few meters away using a telephoto lens/focal length.
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>.
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.
Avoid the use of processing that artificially boosts contrast or artificially boosts colors.


==Collaboration==
Using the in-camera flash head-on usually results in high glare, hard shadows, and poor color rendition, and should be avoided.
'''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==
'''Indirect flash''' (e.g. via a white ceiling, to your rear) provides uniform, soft lighting.
'''Any photo is better than no photo.'''
See e.g. [https://www.youtube.com/watch?v=1mF9UHK8LwU this tutorial video] (TL;DR: [https://youtu.be/1mF9UHK8LwU?t=743 here's the crucial bit]).
Prefer high-resolution, in-focus photos.
In a pinch, use a home-made retroreflector on the in-camera flash, e.g. [https://thecraftingnook.com/diy-flash-bouncer-dslr-flash-reflector/ like this].
Manually setting a high flash exposure (+2 or +3 is not unusual on rear-bounce) and using a high f stop helps put a large part of the image in focus.


Don't use photos from other websites if you think it will upset the owner of the photo.
Taking photos outside on an overcast but reasonably bright day can work too, but since you can't easily control ambient light intensity, this is tricky when CRT traces or displays need to be in 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.
 
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.


Prefer photos without the in-camera flash. In-camera flashes usually result in high glare, hard shadows, and poor color rendition. 
Tips for '''photographing CRT traces''':
Using a high f stop and indirect flash (e.g. via a white ceiling) helps put a large part of the image in focus.
* put the camera on a tripod
See e.g. https://snapshot.canon-asia.com/article/eng/5-simple-bounce-flash-photography-tips
* use low ISO and a high f stop, resulting in a longer exposure time
 
* turn ''down'' the camera's exposure compensation control (i.e. towards a darker image) – auto-exposure wants to balance lighting across the image, often causing the trace to become over-exposed
File names should be relate to the subject of the photo. Cameras generate semi-arbitrary filenames.
* lower trace intensity to avoid blooming and visible artefacts - the camera will make up for the lower intensity in longer exposure time
Those should be replaced with more meaningful names before the files are uploaded.
* lower graticule lighting intensity accordingly
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===
<gallery>
<gallery>
Tek_524_trace.jpg|Hard shadows are distracting
Tek_524_trace.jpg         | Hard shadows are distracting
Tek_524ad_front.jpg|Same subject, but without hard shadows
Tek_524ad_front.jpg       | Same subject, but without hard shadows
6r1a_front.JPG|Good photo, taken outside on a cloudy day
6r1a_front.JPG           | Good photo, taken outside on a cloudy day
Tek_rm547.jpg|Hard shadows, but still a useful photo
Tek_rm547.jpg             | Hard shadows, but still a useful photo. Trapezoid distortion could be avoided easily.
Tek 511a 4.JPG|Low resolution image
Tek 511a 4.JPG           | Low resolution image
Tek_1L60_from_fiche.jpg|Low quality image taken from documentation, much better than nothing
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]].
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_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_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_11a33_rearleft.jpg   | Good photo of the inside of an [[11A33]]. Plenty of light, but not too much glare. Colors and textures are realistic.  Good depth of field (board as well as higher components are in focus).
Tek-7623A.jpg|Good CRT traces and a good picture of the front panel in one photo. Rare.  
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_11a33_inputrelay.jpg | Macro closeups can be interesting, particularly when they illustrate something important.
Tek_1l5_front.JPG|This image suffers from nonuniform illumination.
Tek_1l5_front.JPG         | This image suffers from nonuniform illumination.
Type_m_front.jpg|Hard shadows from light coming from below. It seems unnatural.
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_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_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_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.
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.
5ct1n-crop.jpg            | Perspective distortion (note "diverging" binding posts) caused by wide-angle, close-up shot.
Tek_7b85_front.jpg        | Front panel shot at a longer focal length to avoid excessive perspective distortion; precise focus on front panel lettering.
</gallery>
</gallery>


Line 204: Line 220:
</gallery>
</gallery>


==See Also==
=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
 
=See Also=
* [[Tasks]]
* [[Tasks]]


[[Category:TekWiki]]
[[Category:TekWiki]]
<headertabs />
Retrieved from "https://w140.com/tekwiki/wiki/Special:MobileDiff/75634...92654"