Help:Writing a repair guide

Writing a repair guide
Page types, structure and house style for RTC Wiki repair articles

Most pages on the RetroTechCollection Wiki are repair guides. This page explains how to write the three standard guides for a machine, what each should contain, and how pages on this wiki are written.

Page types

Almost every machine on the wiki has four pages:

Page	Purpose	Title
Machine page	What the machine is: history, specifications, hardware, known faults, documentation	`Machine name`
General maintenance	Cleaning, inspection, voltage checks and the parts that fail	`Machine name General Maintenance`
Troubleshooting	Fault diagnosis, from symptom to cause to fix	`Machine name Troubleshooting Guide`
Capacitor replacement	The capacitor list and the recap procedure	`Machine name Capacitor Replacement Guide`

Some machines also have specialist guides, such as a memory upgrade or a video modification. Topics that apply to many machines have their own pages; link to them instead of repeating them:

Before you write: sources

A reader must be able to check every figure on the page. Before writing, find the manufacturer's documentation: the service manual, the schematic and the parts list. Many are already hosted here; check Category:Service Manuals and Special:ListFiles first.

Cite every value, voltage, part number and date to a source that states it. See RetroTechCollection:Citing sources.
Check that the source is for the same machine and board revision. A figure from a sibling model's manual is not a source.
If you cannot find a source for a figure, leave it out. A missing value is safer than a plausible one. Say what the manufacturer did or did not publish: "IBM's hardware maintenance manual lists FRUs only and gives no component values."
Your own bench measurements are welcome. Say that they are yours and give the conditions: board revision, test point, load and meter.
Do not invent service intervals. Figures such as "replace every 10–15 years" or "re-grease every 2–3 years" have turned out to be made up every time they were checked.

General maintenance guide

Start with a board photo and a one-paragraph introduction to the machine and its age. Then, in this order where they apply:

Identifying the board revision, if there is more than one
Regular cleaning: case and keyboard, then the board
Power supply and voltage checks, with a table of the rails and their tolerances
Connector and socket corrosion
Capacitors: a short summary linking to the capacitor replacement guide
Common failure points: a table of the ICs and parts that fail, with part numbers and symptoms
Voltage and clock test points
Recommended tools and consumables
A preventive maintenance checklist

Give expected values with their tolerances and their source. For example, Apple specifies the Apple IIe +5 V supply at ±3 %, which is 4.85–5.15 V.^[1] Do not copy a tolerance table from another machine's page: the same table has turned up on dozens of machines it does not apply to.

Troubleshooting guide

The troubleshooting guide is built from symptom tables, one per fault area, with three columns:

<templatestyles src="Template:StyledTable/styles.css" />
{| class="wikitable styled-table" style="width:100%; text-align:center;"
|+ '''No video'''
|-
! Symptom !! Probable cause !! Action
|-
| What the user sees || What is likely wrong || What to do about it
|}

Typical sections are: preliminary and power-up checks; a voltage reference table; no power; no video; memory and ROM faults; audio faults; keyboard and input faults; disk or media errors; component-level tests (clocks, reset, chip-level checks); and flowcharts for the common faults.

In each table:

list the most likely cause first
make every action something the reader can do: name the test point and the expected value from the schematic. "Measure +5 V at pin 8 of the 6502" is useful; "check the power supply" is not
link to the maintenance and capacitor guides where they cover the fix

Put faults reported by the community in the symptom table where they belong, not in a separate section.

Capacitor replacement guide

The capacitor list is the point of the page, so it must come from a source: the manufacturer's parts list or schematic, or a community list that was made from the board, such as a Console5 wiki page or Recap-a-Mac. Cite it, and say if it is a secondary source.

The guide needs:

the signs of failing capacitors (link Capacitor Failure Symptoms)
the capacitor list
differences between board revisions
the replacement procedure, as numbered steps
recommended tools and parts
voltage and ripple checks after the recap

Capacitor table format:

{| class="wikitable styled-table" style="width:80%; text-align:center;"
|+ '''Board name capacitors'''
|-
! Ref !! Capacitance !! Voltage !! Type !! Notes
|-
| (designator) || (value) || (rating) || (electrolytic, tantalum...) || (source, location)
|}

Check the finished list against these warning signs. Each one has been found in lists on this wiki that turned out to be invented:

long runs of consecutive designators with the same value (C1–C20 all 10 µF); real boards are not numbered that way
every voltage rating the same
a voltage rating at or below the rail the capacitor sits on
a "function" column that no source gives
a regulator, fuse or supply rail that the board does not have

Where a machine had different power boards for different mains voltages, give each board its own table and say which is which.

House style

Pages on this wiki are written in plain, specific, encyclopaedic English. Short declarative sentences, specific values and named parts:

Write this	Not this
The Macintosh IIci was introduced on September 20, 1989. It uses a 25 MHz 68030.	Introduced on September 20, 1989, the Macintosh IIci stands as a pivotal entry in Apple's modular Mac line, boasting a powerful 25 MHz 68030.
Measure the C64 power supply's 5 V output before connecting it. A failed supply can put too much voltage on the board and damage the PLA, RAM and SID.	The C64's original power supply, a testament to early consumer electronics design, can experience voltage drift over time, underscoring the importance of regular verification.
Discharge the CRT. Measure the 5 V rail.	It is important to note that you should always make sure to discharge the CRT before proceeding.

Do

Use plain verbs: is, has, uses, fits, fails.
Write instructions as commands: "Remove the four screws."
Give exact values and part numbers: "Nichicon UKW 47 µF 16 V", not "a suitable capacitor".
Repeat the machine's name. Say "the C64" again rather than "the beloved breadbox".
Be definite where the source is definite, and hedge only where it hedges.
Use British English.
State hazards plainly: mains voltage, stored charge in the CRT and the PSU capacitors, what can kill you. Then let the reader decide. Do not tell readers not to open a power supply; recapping one is a normal repair.

Avoid

These patterns are typical of machine-generated text. Rewrite the sentence; do not just swap the word.

Pattern	Example	Instead
Significance and legacy	"marks a pivotal moment", "cemented its place"	The fact itself, or nothing
Trailing -ing clauses	"..., ensuring reliable operation"	End the sentence at the fact
Puffery	"powerful", "iconic", "legendary", "boasts"	"has", with the number
"Serves as", "stands as"	"The PLA serves as the memory manager"	"The PLA is the memory manager"
Not X but Y	"not just a computer, but a platform"	Say what it is
Talking to the reader	"It's important to note", "Keep in mind", "Here's why"	State the fact, or give the instruction
Talking about the page	"This page previously listed...", "no source could be found"	State the fact about the manufacturer: "Apple published no parts list for this board"
Unsourced attribution	"enthusiasts often report"	Name and cite the source, or drop it

Never add a "correction" or "what changed" section. Explain changes in the edit summary.

Formatting

Headings in sentence case: "Power supply checks", not "Power Supply Checks". No emoji in article headings except for a high-voltage warning.
Bold the page subject once, in the first sentence. Do not bold phrases, values or list labels.
No em dashes (—). Use a full stop, comma, colon or brackets.
Numbered steps where order matters, bullets where it does not. Write list items as whole sentences or short phrases, not "Label — text".
Data tables use class="wikitable styled-table" with <templatestyles src="Template:StyledTable/styles.css" /> once before the first table. A table of two or three rows is usually better as a sentence.
A board photo at the top of maintenance and capacitor guides: [[File:Name.jpg|thumb|360px|Caption]].
End with the platform category and the guide-type category (see Help:Categories), and the manufacturer's navbox if it has one (see Help:Templates).

Links

Every repair guide should link to:

the machine page
its sibling guides (maintenance, troubleshooting, capacitor replacement)
the cross-machine pages it relies on, such as CRT Discharge Procedure for any machine with a CRT and Battery Explosion, Capacitor or Corrosion Damage for any machine with a battery

Link each term once, where it first helps the reader.

Before you save

Does the first sentence say what the page is about, plainly?
Does every figure have a citation, and does the source say it?
Is the capacitor list from a source, and free of the warning signs above?
Are part numbers, values and voltages specific?
Are there any trailing -ing clauses, puffery words or bold labels left?
Are tables in the styled-table format?
Are the categories and sibling links there?
Does a CRT page link CRT Discharge Procedure, and a battery page Battery Explosion, Capacitor or Corrosion Damage?

References

↑ Apple II Reference Manual – For //e Only, Apple Computer, Inc., 1982, Table 7-2. Hosted as File:Apple IIe Reference Manual 1982.pdf.