Wiki Home arrow MediaPortal Wiki

Documentation Writer's Guide

Contents

  1. Quickstart
  2. Roadmap
  3. Detailed guide
    1. Document structure
    2. Navigation
    3. Writing style
      1. Text formatting
      2. Hyperlinks
      3. Layout
    4. Illustrations
    5. Legal guidelines
    6. Access Control Lists
    7. Further reading

1. Quickstart

The MediaPortal documentation is a collaborative project, where anyone can contribute straight from their webbrowser. No downloads or installs are needed, but you must create a useraccount first on the UserPreferences page.

After that, please follow these guidelines for adding or updating documentation in the MediaPortal wiki:

  • Have something to add to the wiki? First use Search to see if it is not already in the wiki, and to find the best location to add it.

  • Edit any page by pressing Edit at the top or the bottom of the page

  • Create a link to another page in the wiki using the following code: [:document title:link text]. Document title is the name if the page you want to link to, link text is the text you want to be clickable.

  • See HelpForBeginners to get you going, HelpContents for all help pages.

  • Use BlueTwo as skin for all screenshots, except you want to describe a skin related feature (for example the Basic Homescreen of the ProjectX Skin).

<!> Please use the WikiSandBox to experiment with editing or download MoinMoin Desktop Edition, a standalone Windows version of MoinMoin.

2. Roadmap

So you want to help out with the MediaPortal documentation? Please take a look at the documentation roadmap to see what needs to be done.

3. Detailed guide

3.1. Document structure

#pragma section-numbers 2

= Document Title =

[[TableOfContents]]

== Introduction ==

Here you will write an introduction on the topic.

== Main section ==

=== Subsection ===

Etc, etc, etc...

----

<< Back to [:PageTitle:parent document].

Note that the processing instruction #pragma section-numbers 2 will keep the document title out of the table of contents.

3.2. Navigation

Keep in mind that people can start reading the documentation from any page, especially after using a search function. They need to be able find where they are inside the documentation, and how they can navigate further. Always provide links that go up, back, and further in the documentation structure.

3.3. Writing style

3.3.1. Text formatting

  • Bold: Labels of GUI elements, for example icon titles, menu items, button labels.

  • Italic: Accentuated text, for example to highlight differences or possibly confusing terms. Only use for up to 4 words at a time.

  • Monospaced: Short texts to be typed by the user. 

  • Monospaced block: Larger amounts of text to be entered by the user, or contents of text-files.

  • Strike through: Text that is not valid or current anymore, but for some reason is still needed. For example to strike out completed items in a progress report.

  • All other text formatting should be avoided!

3.3.2. Hyperlinks

Hyperlinks form the power behind the wiki, so use lots of them. And make sure the text on the hyperlink describes the page the link leads to. Some examples:

3.3.3. Layout

Writing or editing documents, the temptation is often very big to also format the layout of the document. As a general rule of thumb, please don't do this!

Some examples of custom layout which should not be used:

  • Adding extra whitespace above or below elements ("empty lines") by inserting forced line breaks.
  • Indenting ("jumping in") paragraphs.
  • Adding horizontal rules ("lines").
  • Formatting lines as headers by making the whole line bold or italic, instead of using the build-in heading codes.
  • Skipping a header level because the next one looks better.

Layout formatting should instead be performed by a (set of) centralized, overall applied documents called stylesheets. There are a few important reasons for this:

  • Layout actions performed in the wiki code, have to be (manually) repeated on each and every wiki page. While layout code in the stylesheets only has to be defined once to automatically be applied to each page.
  • Not every editor would know about any style guidelines, and different editors will have different perceptions of what is the "best" layout. As a result, even on a single page, several different layout styles would be applied. This causes very chaotic and unprofessional looking pages. We don't have the resources to check every page after it's been edited to apply all the indenting dots and hard linebreaks that may have been forgotten or added in wrong places.

  • What looks good in your browser, may not look good in another. While Internet Explorer and Firefox will display most layout (almost) the same, the layout will look very different when browsed by phone browsers, show in the Documentation plugin, or published as printed documentation. Stylesheets can easily be coded to display optimized on many different outputs.

  • A centralized layout would also allow us to adjust the whole site to a new design, which would require lots more work when the layout is hardcoded in the pages.

  • And last but not least, stylesheets offer far superior layout possibilities compared to what is possible with wiki-code.

3.4. Illustrations

  • Using the right image formats for illustrations, ensures high quality illustrations while keeping filesizes down.

    • JPEG: for photo's and graphic intense screenshots (like of the MediaPortal interface). Preferred quality factor is between 75% and 85%.

    • PNG: for graphs, logo's and screenshots of regular Windows programs and dialogs. On average this will produce smaller file sizes, plus it will prevent the noise and blurring you get with JPEG images. Transparency can be used, but keep in mind that Internet Explorer only supports alpha transparency from version 7 and up.

    • GIF: when you need simple animations, and for images with very few colors (no gradients). Note that not all output devices (for example PDF documents) supports animation.

  • Resize large screenshots. Maximum width should be 500 pixels, to make sure the pages can still be read on low resolution screens (for example standard-definition TV's).

3.5. Legal guidelines

  • It is not allowed to attach or otherwise insert copyright protected material, without the consent of the owner. This includes texts, fonts, images, software, music files, etc. If you are unsure about the material you want to attach/link to, then get in contact with a moderator.

  • It is not allowed to post tutorials and/or link to webpages which contain applications or tutorials for performing illegal activities, such as
    • Sat-Hacking (SoftCAM, Card-Emulation, Card-Sharing, MDAPI etc.)

    • CopyProtection removal (DVD's, HD-DVDs, BR-Discs, etc.)

    • DRM removal
    • Illegal use of software
  • Be aware that our servers are hosted in Germany and thus are subject to German law. Please do not expose us to any unnecessary legal liability.

3.6. Access Control Lists

It is possible to define who is able to view or edit wiki pages by using an Access Control List (acl). To use these, you must have admin rights on a page. An Access Control List is created by placing a processing instruction like the following at the top of a page: 

#acl -SomeUser:admin +SomeGroup:admin Known:read,edit All:read

Access Control Lists are always evaluated from left to right. The above example defines the following rights:

  • Anybody can read the page.

  • "Known" users (people who are logged in) can read and edit the page.

  • Members of SomeGroup can administer the page (in addition to reading and editing, because of the plus sign in front of the group name).

  • SomeUser cannot administer the page, even if he is a member of SomeGroup (because of the minus sign in front of his name).

The following system groups are defined by MoinMoin:

  • All: everybody, even if they are not logged in.

  • Known: users who are logged in.

  • Trusted: logged in users who used an authenticated connection.

In addition, the following groups are defined in the MediaPortal wiki:

  • TesterGroup

  • DesignGroup

  • DeveloperGroup

  • DocsGroup

If the ACL does not resolve for a given user, then the user does not even get the right to see the page. For example, users who are not logged in, cannot view pages where the All group is not included in the ACL.

It is not possible to assign rights to parts of pages. However, you can store a section as a separate page, give that page an ACL, and then include that page in the main page using the [[Include(...)]] macro.

For more information, see http://moinmo.in/HelpOnAccessControlLists.

3.7. Further reading

Find more information in the MoinMoin Page Editing document.

<< Back to Contributor's Guide

MediaPortal Wiki: DocumentationWritersGuide (last edited 2008-05-11 09:06:40 by pbb)
by team-mediaportal.com - 2008 SourceForge.net Logo