Style Guide

From Digi Developer

Jump to: navigation, search

Contents

Text Formatting

First, see metawikipedia:Help:Wikitext examples, mediawikiwiki:Help:Editing pages, mediawikiwiki:Help:Formatting for introductory material on MediaWiki's wikitext formats and general guidelines. Please be aware that installs of MediaWiki due to versioning or installed modules may provide slightly different sets of formatting tags, and not all tags will work on all wikis.

  • As mentioned in mediawikiwiki:Help:Formatting, please do not use first level headers due to their formatting similarities to the page title.
  • When referencing filenames, variable names and keywords inline, use italics to highlight names.
  • Use boldface to highlight literal objects/values such as None, class instance references, etc..
  • Always use source highlighting for any language or snippet where highlighting is available.
  • Page text should be allowed to wrap naturally in paragraphs. Be careful that you are not introducing line wraps unnecessarily. This is particularly easy to do when copy and pasting content from external sources.
  • Argument lists, descriptions of variables, etc should use definition lists. These are set-up in wikitext with semicolon for the term, and color for indented descriptive test following the term.

Page naming

Page naming and organizational practices?

  • Page titles should be a short concise description of their contents. The page title does not need to be a complete sentence and should not end in a period.
  • Since external search engines place a high value on the page name, using a page name such as Reading digi realtime clock is better than DRTC_P1 or digirealtimeclock.

Meta information

  • We're following Wikipedia's lead. Use Templates to flag pages for status progress or problems. We can then use the "What links here" query for the template to find all such problematic pages.
  • Please use Categories liberally and usefully. The more we can have a taxonomy of information and ways to search through our content, the better users will be able to find the data they are looking for. Any one page can be in many categories at once, so for example a page explaining use of the Digicli module to read/write the Digi RealTimeClock might be both a 'digi module' and a 'hardware' category. MediaWiki category use is explained here: MediaWiki:Help:Category, but as example the Digi Modules include this line at the end of their page:
[[Category:Digi Provided Built-in Modules]]

Code

  • Please follow standard well accepted style guidelines for Python coding. PEP-8 Python Style Guide and PEP-257 Docstring Conventions are good places to start
  • Please follow a consistent internal versioning practice in packaged code. Snippets provided directly on the wiki are fine using wiki history alone, but for larger code delivery, please take advantage of version control revision tags that are clearly communicated with the packaged code.
Personal tools
Wiki Editing