Difference between revisions of "Contribution Guide"

From Unofficial Zero Manual
Jump to: navigation, search
(link update)
 
(No difference)

Latest revision as of 03:54, 31 March 2020

Registration

To contribute, we do require that you register.

You do not need to provide any personal information (and we do not use any information provided), but the wiki does validate the email contact information so that we can track edits and deal with spammers.

Sign up to edit here.

Solicitations

The simplest and easiest way to contribute is to ask for information in an appropriate place.

This can help in a number of ways:

  • If the information has already been posted somewhere on the wiki:
    it points out that an editor should link to it where it was requested, either subtly or with a very obvious callout.
  • If the information has not been posted, but is known:
    it will prompt another editor to expand the stub with a basic entry.
  • If the information is not known:
    it will prompt someone in the community to try to find it.

Solicitation Placement

Where to ask for information:

  • Main Page discussion covers general website feature requests.
  • Unofficial Service Manual discussion includes requests for more information about the vehicles themselves.
  • Within a Page is perfectly appropriate where the page outline has a suitable heading for the information but no entry underneath it for the type of thing to document.

Types of Contributions

Terms

See the "term" category for pages that describe terms of art used by Zero or others that are not commonly known, so deserve explanation.

If you cannot find a term that you have heard (but not one you have made on your own)

Products

See the "product" category for pages describing products made for the Zero, whether OEM accessories or the aftermarket.

There's a little editorial discretion about generic products or noteworthy products.

Basically there's room in the Aftermarket page contents for most products, so items with separate pages should be more notable in some sense.

Photos

Parts Illustrations

Photo editing can help contribute to illustrations.

Guidelines
  • Try to take a photo of the part where it is on the bike.
  • Try to take a photo of the part separate from the bike.
  • Use a white or single-color background with good lighting to see the part's features clearly and help eliminate distractions.
  • When labeling a part photo, upload both the labeled and unlabeled versions for comparison.
  • Each photo gets a wiki page; labels can be annotated there if there is a doubt about how to label something in software.

Instructional Illustrations

The goal is to improve a set of instructions by photographing part of a process.

See the "procedures" category for existing separate pages for this purpose.

Guidelines
  • Center the part being operated on in the photo, and zoom in enough to exclude anything not relevant.
  • Get as much light on the subject as is needed to read text or understand how to use a tool in context.
  • Include before and after shots if it helps clarify what's to be done.

Diagrams

These require the most preparation and knowledge, but can be strategically helpful for understanding how to troubleshoot.

Sounds

Describing sounds in text is very difficult, and benefits from appropriately-linked recordings.

Normal Sounds

If you can sample the sound of a normal operation, uploading it with a reasonable name will highlight that need to an editor who can find out where to include it.

Abnormal Sounds

If you can sample the sound of an abnormal condition, uploading it with a name indicating what problem it is meant to highlight will help an editor identify where to include it.

Instructions

The goal is to guide owners through a process, and to have as much guidance as possible without confusing the reader or leading them to accidentally damage something.

See the "procedures" category for existing separate pages for this purpose.

Guidelines
Indicate what equipment or vehicle model-year was used for the instructions until someone with a different model or year helps confirm that theirs works or whether a variation is needed.
Write explicitly about what to do, in order.
List tools and parts ahead of the instructions as much as possible to help the reader prepare.
Write explicitly about what the reader should expect to see.
Add safety notes when the reader might accidentally break something.
When in doubt, indicate incompleteness.
Incompleteness is okay as long as it's mentioned so that the reader understands where they need to improvise and improve.
Style
Prefer an outline format with one sentence per line.
Lead sentences with the primary verb and then the primary subject.
The purpose of a step or action should generally be listed below/within the step; the action is the thing to read, and the purpose helps prepare.
Any verification steps should be listed before their dependency, so the reader performs them in order.

When in doubt, just dump your thoughts into a paragraph on the page, and maybe flag it for an editor to revise later however feels appropriate to you.

It's better to have your content in any form at all, and fix it later.

Skills

The skills page deserves attention for helping owners learn how to responsibly work with or repair electrical or mechanical systems in a generic way.

Solicit a how-to there if you don't know how to do something, or try to provide it if you've been formally trained on the subject.

In any case, try to link to relevant and responsible guides on the internet as much as possible, so we don't have to maintain too much ourselves.

Troubleshooting Guides

Troubleshooting an electric motorcycle is a new topic.

Even the OEM seems to still be evolving how best to train its in-house and dealer technicians to work with the vehicles efficiently and safely.

Please solicit troubleshooting for now on the troubleshooting talk page until we understand how this could best be done.

Hacks

Check the Advanced Modifications page for any How-To guides that require fabrication or alter the original vehicle in unsupported or (potentially) warranty-invalidating ways.