Documentation

So you want to help out...

As with the WebOS Ports project as a whole, this wiki lives or dies based on your participation and willingness to help out. If you're not a programmer or developer per se, but you're good with words and want to help, we could use your expertise!

Making Contributions

Everyone is welcome and invited to help with the wiki. The only caveat is to be sure whatever you contribute you have the right to contribute. That said, we invite anyone who is an authority on some material that is appropriate for this wiki to add their knowledge for the benefit of the WebOS Ports community. We appreciate it!

We use templates, templates, templates!

This wiki has many thousands of web pages including articles, contact lists, walkthroughs, and much more. To make it easier to maintain, the wiki has been designed to avoid duplicating information in many places, which would require a lot of work to keep up to date.

Instead, this wiki uses a feature called templates, which is a way of breaking a wiki page into small bite-sized chunks, each of which can be included by reference, or "transcluded" into another page.

One thing that's neat about transclusion is that a page can include a template which is itself made of multiple pages. In fact, a template can even intelligently determine which page is transcluding it, meaning it can alter its content depending on the context.

Sound a little confusing? Do a little reading up on templates, and it may start to make more sense. But in essence, it comes down to this:

The WOP Wiki Golden Rule:

NEVER DUPLICATE INFORMATION.

That means that if any chunk of information needs to appear in two places (such as on two separate pages), first create a template, then transclude that template into the new page(s). If something about that chunk of info should change, you only have to change it once, and the two pages that use it will automatically get the change "for free".

Fixing Problems: The Plan

How to fix a problem:

1. If the problem is something very simple, like a typo or other minor change, feel free to fix it on your own.
2. Some problems, such as incorrect information for a device, should be changed in the device template, which is a page full of "settings" that describe that device. An example of this might be the wrong screen dimensions, or the build instructions showing the wrong branch (such as "jellybean" instead of "gingerbread".) A simple fix to the device template settings should resolve this.
3. If the problem is more substantial than either of the above scenarios, and you understand how wiki templates work, and you are able to make the change to the Template without negatively affecting any other page that may be using that template, feel free to fix it!
4. If you are unable to resolve the issue on your own and would like someone else to look at it, report the problem on the Wiki Problems page, and hopefully someone will take a look.

Using the Device Template

There is one kind of template that's very special on the WOP wiki, and that's the template for devices. Examples of devices include, say, a tablet, or a smartphone, or an android-based game console, or whatever. The Nexus 7 tablet (codename: "grouper") is a device. So is the HTC Desire Z smartphone (codenamed "vision"). A device is a single piece of hardware that has its own development repository and therefore its own unique distribution of WebOS Ports.

The device template is a special wiki template that's used to store ALL the information about a single device that is used to automatically generate custom build instructions, device info pages, installation walkthroughs, and more for that device. There's only one device template per device, and it includes all the characteristics for that device that can be used to build wiki pages using the templating system.

So, using a device template, we can create a very generic set of installation instructions, and have those instructions automatically customized for each individual device. When a new device comes along, we won't have to rewrite the installation instructions for that device. Instead, by filling out the device template, the installation instructions can "build themselves" to match the requirements for that device.

If this doesn't make complete sense yet, keep reading. Hopefully you'll get the gist of it.

How device templates work

A device template has the following name:

Template:device_CODENAME

where CODENAME is the code name for the device. To create a new device, say, with a code name of "bambi", you'd create a new page at Template:device_bambi.

But what do you put in this device template page? We've created a nice, fresh, blank for you to use as a base. It's located, appropriately enough at Template:device_CODENAME. Start with this page, and copy its contents. Then paste it, again using our example, to the page at Template:device_bambi. Next, modify its contents, choosing appropriate parameters and values for this device.

When you're done, head over to the devices page. More information can be found there on how to add your device to the list and quickly create an info page, installation instructions, and more.

Wiki roles

As a new visitor, you may not be able to edit any page or template you want. But if you can prove that you are a competent editor, you may be given additional privileges to help maintain and develop the wiki.

Just as the individual devices have developers who are responsible for maintaining the source code for that device, we hope we'll have volunteers to keep the wiki up to date for devices and device families (like tablets that are all made by the same company for example).

More info on the various roles and how to apply to get elevated editing privileges are forthcoming.

A first attempt at a style guide

If you're going to be editing text, or even creating new pages, here's a quick go at some style pointers. Read it carefully.

1. Make it easy to read/digest for anyone. Not just technical people.
2. Don’t dumb it down though. The audience is your typical non-professional, non-IT end user with an interest in learning what WOP is, and why they would use it. And yeah, there’s some smaller percentage of them with a bit more experience who might want to actually start hacking their devices themselves.
3. The goal is to make it EASY for visitors to learn. It’s not meant to be in any way elitist or to create artificial hurdles to learning. The wiki is here to help people.
4. Tone should be irreverent and informal. This is fun stuff. But keep it accurate and as compressed as possible without being overly dry and boring.
5. Include references and links to other sites whenever possible. Never be afraid to send someone to another site if it’s relevant to the topic-- this includes other ROMS or wikis.
6. When writing step-by-step instructions, start with a bolded header that explains the goal, ending with a colon. (To do some operation, follow these instructions:) Then number each step individually using the wiki list tag. Keep each step super-clean and simple.
7. Use active, present-tense verbs in instructions. (“Double-click on the icon...”)
8. All on-screen menu items should be bolded and listed from most general to most specific. So present the information in the order that the user will encounter it. Also, use text (“Under the File menu, choose Open File...”) rather than shortcuts like File->Open File. It’s better to standardize this in as clear a manner as possible. The extra work of typing out the steps will pay off for the reader.
9. It’s also a good idea to tell the user what to expect from an action. (“If all goes well, your build should now begin.”)
10. All terminal activity should be presented in Courier using the <code> and </code> tags. Always indicate what text comes from the computer vs. what is entered by the user. Precede console inputs with a "$" to indicate user input.
11. Similarly, any reference to file names or directories within text should also be in Courier. (“Look in the /data directory for a file called README.TXT.”)
12. When accurate grammar is needed, check with Strunk and White. (But that doesn’t mean you can’t use slang and shitty grammar-- as long as you’re clear. Just sayin’.)
13. Coordinate your pages w/a designer. We should have an uniform, appealing layout and color scheme. Plus tons of screenshots and such are always nice to look at.