User:Aeric/Style Guide

1 Logos

Logos need to be 160px wide X 135px tall. Using Adobe Illustrator to create one, I found that:

• Like all graphic programs, it sizes to the amount of stuff on the page, so you have to put a box in the background to get the size you want.
• Creating a box 160px wide produced 160x wide output
• But a box that was 135px tall produced output that was too tall!
• Double checking 20 or 30 times, there was nothing extending outside the box!
• Making the box 122px tall generated 135px output.

2 Diagrams, Images, and Screenshots

2.1 Uploading an Image

There does not seem to be any way to upload images en masse, short of finding the APIs and writing a program to do it. So each one must be added manually:

• In the sidebar, click toolbox > Upload File.

Tip: After uploading a new version of an image, delete the old version to minimize the wiki's footprint. (There doesn't seem to be a way to automatically purge file history-- although there are multiple scripts that seem like they should do it.)

2.2 Creating an Image

Photoshop for Screenshots (old)

• In Photoshop capture and save screenshots as .psd format.
• Crop images to 750px wide, then Save For Web as .gif
• When necessary, use Image Size in Photoshop to reduce wide images, however this often results in poor readability. It is a better practice to frame the browser window so that all elements fit naturally in a 750px space. Sometimes it is necessary to "cheat", and manipulate image elements manually so that the resulting image is of good quality and readability - avoid this if possible.
• In the wiki, use Upload File to load a file to the \Images folder

SnagIt for Screenshots & Basic Graphics

Taking screenshots is easy in SnagIt, and the editing features are good. But the text in the image tends to be way larger than the Wiki text, unless you resize it. (You can do that in SnagIt, before saving.)

Resizing to 75% works well, and that's an easy selection from the SnagIt menu.

Adobe Illustrator for Callouts

AI is good for adding objects to a background image, without modifying the image:

• Take SnagIt image, scale to 75%, and save as {name}-base.png
• Open AI. Create {name}.ai
  -or-
• File > New From Template

  Choose relationals/techpubs/images/templates/callouts.ait

• Import graphic
  • File > Place (link to link to the file, instead of copying it in)
  • Use the Link Tool to manage links (Window > Links)
• Add callouts
• Export as {name}.png
• 12pt Arial font works well for numbers after the image has been resized down 75%

SmartDraw for Diagrams

SmartDraw is easy to use, with lots of pre-built components in its libraries. The best way to create the diagram:

• Use 8-point font as the base font in the image (8-point Verdana for text)
• Use 10-point Arial (italicized is good) for major headings
• Save the image at 80% size.
  (Otherwise, the text is far too large when viewed in the wiki.)

3 Writing an Article

• Start with a concept, a description of the feature; art or some screenshot is good to show (top right)
• User permissions
• How-to (...accomplish a thing)
• Considerations (bulleted list of disclaimers)

4 Naming Articles

• Each wiki page is named to match the name of the feature; this is important because users search for what they see in the UI, and MediaWiki makes every page searchable
• Add a Category to each page; this makes the page available from the Category Tree
• When adding a new article, consider if it should be added to any of these Categories as well:

• Overview
• Core Concepts
• Glossary
• Learning Resources

• API pages may have a prefix, i.e., REST API:field Resource, because the term 'field' is too common and used elsewhere on the site

5 Wiki Conventions

• To make it easier to go from the GUI to the Wiki, the Wiki tries to have a page for each section heading in the GUI. In most cases, it should be possible to search on a section heading, to find the material you're looking for.

• From any given page, you can use "What links here" to get more information. (Links tell you where material is used, "transclusions" point to pages that provide a larger context.)

• When you follow a link to a Wiki page, it sometimes raises the question, "Where is this section in the GUI?" To help answer that question, pages that correspond to GUI sections have a GUI path at the top. Those paths tell you what actions you take to get to that section of the GUI. The general format of a path looks like this:

Do this > Then this > And this

This sample shows the kinds of the things you might see in a GUI path:

Item > {choice} > [Button]

where:

• Item - Typically an item in the navigation pane. Could also be a menu item.
• {choice} - A selection you make or a value you enter
• [Button] - A button you click

Note: Text you enter is often indicated in italics. But it may also be shown in monospaced font, if it pertains to a file, directory path, or code.

6 GUI Pages

In the ideal world:

• Every tab in the GUI has a help icon
• Every help icon goes to a page that has "GUI breadcrumbs" at the top, and an H2 heading in the topic for each section heading in the GUI page, so the TOC lets users zero in on a particular section.

6.1 Breadcrumbs

"GUI breadcrumbs" at the top of the page record the shortest path through the GUI to the item in question. The give users a way to get to the material in the platform, after they have searched the Wiki or followed a link to find material of interest.

Sometimes, it's helpful to have two sets of breadcrumbs, one for users and one for designers. In that case, labels are added to identify the audience they're intended for:

View Data: Workspace > {object} > {record} > Related Information Customize: Designer > Presentation > Forms > {form} > Related Information

More commonly, though, only one set of breadcrumbs is supplied. In that case, no label is necessary.

6.2 Sections

A GUI page typically has multiple sections. Each section should ideally be represented by an H2 head in the Wiki page, so there is a one-to-one correspondence between the section headings in the platform and the top-level headings in the Wiki page.

The last heading on the page should be "Learn more".

The GUI pages should be "minimal", and rely on links for relevant information:

Concepts

The element "Xyz" should link to an "About Xyz" topic so that someone familiar with the information isn't burdened by it, but someone new can find it.

Tasks & Procedures

The tasks and procedures that tell users how to do things should be in separate, "Working with" pages. The "Learn More" link(s) at the bottom of the page should link to the those.

Reference

Tables of detailed information that allow users to vary the tasks they can perform should also be on separate pages, with links from the GUI page.

7 "Working With" Pages

A "Working with" page should consist primarily of a series of tasks (procedures) that user might want to carry out. For example: Add an Xyz, or Rename an Xyz.

Conceptual information should be transcluded at beginning of the page, or the beginning of a section, as appropriate. For example: {{:About Xyz}}.

Reference information should be transcluded in the place where it is used, or in a section at the end of the page, if it is either very long or it is used in multiple places.

The directive should be included on that page, to make it easier to refer to the sections in conversation and during reviews.

Note: If appropriate, the "Working with" page may link to GUI pages. (In effect, GUI pages live in a separate namespace. Those pages shouldn't be transcluded, because they link to most of the same material--possibly in a more simplistic way that takes the user away from the current page.

8 Links to "Working with" Sections

Links from other pages should ideally go to sections in a "Working with" page, so that there is surrounding context for the user to explore. The problem is that the links are more difficult to formulate: [[Working with Xyz#Nailing the Xyz|Nailing the Xyz]].

One way around that difficult is to set up a page called "Nailing the Xyz" that has a redirect: #REDIRECT [[Working with Xyz#Nailing the Xyz]]. Links can then be more easily formulated as [[Nailing the Xyz]].

That strategy becomes more difficult if the "Nailing the Xyz" section needs to transclude the topic. The topic would naturally want to come under the heading "Nailing the Xyz", but that conflicts with the desired redirect page.

The solution is to prefix the topic with COMMON, so the topic page is called "COMMON:Nailing the Xyz". That solution kills two birds with one stone:

1. It makes it possible to create a "Nailing the Xyx" topic that redirects to the "Working with" page.
2. It says to anyone editing the page, "This topic is used in multiple locations. Make sure that your planned changes will work in each of them."

If the content isn't reused, then a different prefix is needed. ("About" for a concept, "Task:", or "Ref:", or as a last resort, "Content:".

9 The Category Hierarchy

Categories define a hierarchy, by virtue of defining "category pages" that belong to other categories. But since the categorytree extension is installed (and running in the sidebar) the user never has to view a category page. Instead, each category page looks like this:

#REDIRECT [[Some Page]]

[Category:Parent Category]]

When a user clicks on a category in the category tree, they get redirected to a content page. Meanwhile, the tree shows the other category pages that belong under the category.

Note: The target page for the redirect should always be some form of "Working with" page (whether or not it has that particular name) that encompasses the pages below it in the hierarchy--preferably by way of transclusion.

10 Hacking the Category Tree

The Category Tree is one of the many extensions used in the support wiki. By default, the Category Tree organizes pages in each category alphabetically. See an example of a Category page at: Category:Objects. Note that all the subpages are listed at the bottom of the Category page.

It was important to the design that the Category Tree be able to map UI elements in a specific order, especially Setup. The way to cheat this is by using the MediaWiki "pipe trick".

In the following example, we have three articles that belong in the Setup category:

• Personal Setup
• Customize
• Administration

If the usual Category syntax were added to each page, these articles would be listed in alphabetical order in the Category Tree, which is not desired:

• Customize
• Monitor
• Personal Setup

Using the pipe trick, add following category tags to the pages as indicated:

Article	Category tag (added at the bottom of the article)
Personal Setup	[[Category:Setup| 1]]
Customize	[[Category:Setup| 2]]
Monitor	[[Category:Setup| 2.4]]

Notes

• A space after the pipe "|" is required
• The numbers can be any decimal number between 0 - 9.9
• Only a single number after the decimal is allowed
• Use decimals when there are more than 10 items in a category, for example the Category:Objects page

11 Special Pages

• Mediawiki:Breadcrumbs - Used by an extension that was originally installed for Wiki breadcrumbs, but not kept up to date. (GUI breadcrumbs are more desirable, for GUI pages.)
• Mediawiki:Monobook.css - Add CSS styles to the wiki on this page. Styles defined here override whichever "skin" happens to be in use. (Put stuff here to experiment. When satisfied, move it to the .css file in the skin.)
• Template:ISV - Nav pane for the ISV-version wiki, at isv.platformatyourservice.com
• Template:LJ - Nav pane for the production-version wiki, at lj.platformatyourservice.com
• Template:Tree - The nav pane wrapper that selects one of the previous two. (Transcluded into MediaWiki:Sidebar.)

12 Useful Directives

• #REDIRECT [[new page]] - redirect current page elsewhere
• __TOC__ - put a Table of Contents here
• __NOTOC__ - No TOC on this page
• {{DISPLAYTITLE:page Title}} - Change the capitalization of the page title (must match in all other respects)
• - Numbers the headings in the page to match the numbering in the TOC. Useful for the large mega-documents with lots of transclusions, especially when printing things out for review, so you can find things (printouts don't seem to get page numbers, for some reason).
• ... - ...