Wiki Best Practices

This page describes the recommended best practices for contributing and editing Digilent wiki content. Unless otherwise stated below the Digilent wiki follows the Wikipedia Manual of Style.

• Namespaces
  • Use only lowercase alphanumeric characters and '-'.
  • Use '-' (dash) to replace spaces.
• Page Names
  • Use only lower case alpha numeric characters and '-'.
  • Use '-' (dash) to replace spaces.

• Use present tense.
• Use the imperative mood.
• Avoid addressing the reader directly:
  • Bad: You may think this will work but actually you need to add a stop button to the while loop.
  • Good: Add a stop button to the while loop.
    
  • Bad: Remember to save when you are done.
  • Good: Save the file.
• Avoid unnecessary constructs:
  • Bad: Note that this was naturally subject to controversy in more conservative newspapers.
  • Good: This was subject to controversy in more conservative newspapers.

It is often easiest to think of the wiki as a file system where namespaces are folders and pages are files. This is visible in the page URL where slashes separate namespaces (folders) with the final element naming the page (file).

For example this page, /reference/wiki/start, is a file called 'start' in the 'wiki' sub namespace of the reference top level namespace.

• Navigation Pages are pages that are primarily intended to aid user navigation.
• Content Pages are pages that contain content for users to consume.
• The main page in a namespace should be called 'start'.
  • The 'start' page may be a landing page or a content page.
• Most content pages should be contained in their own namespace. This makes pages easier to move and avoids naming conflicts.
• Favor relative links over absolute links.

• Learn
  • Fundamentals
    • Fundamental engineering concepts (think wikipedia article) that are intended to be linked from or included in other pages to avoid duplicate content.
  • Tutorials
    • Instructructional content designed to be highly reproducible and will often (but not always) contain step by step instructions using specific hardware and software.
  • Courses
    • A collection of lecture, discussion and lab materials. Solutions may not be public.
• Projects
  • Inspirational content that is not designed to be highly reproducible. Providing source code and schematics is encouraged but not required.
• Reference
  • Reference material for digilent products and projects.

• Images
  • Images should be stored in the same namespace as the page on which they appear.
• Source Code
  • Add small chunks of source code inline using the

     tag.
        * Projects and large chunks of source code should be stored in GitHub.
      * **Binaries**
        * Binaries should be hosted on a file sharing service such as Amazon S3.
    
    ==== Tagging ====
    ----
    Use the [[https://www.dokuwiki.org/plugin:tag | Tag Plugin]] to tag pages. Below is an example of the tag syntax:
    <code>{{tag>tutorial programmable-logic basys-3}}

• Tags should be placed after page content (ie at the bottom).
• Use only lowercase alphanumeric characters and '-'.
• Use '-' (dash) to replace spaces inside tags.
• Separate tags with spaces.
• Content pages should include namespace tokens as tags.