Tekwiki Guidelines: Difference between revisions

Jump to navigation Jump to search
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
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
==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==
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.


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


Prefer photos without the in-camera flash.
When photographing an instrument, it's good to also get internal photos.  
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,  
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.


When photographing an instrument, it's good to also get internal photos.  
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.  

Navigation menu