Skip to content

Latest commit

 

History

History
139 lines (105 loc) · 9.69 KB

DocumentationStandard.md

File metadata and controls

139 lines (105 loc) · 9.69 KB
Raw
layout
default

{% include links %}

  • TOC {:toc}

This is a standard for contributing to this documentation (SeLite.github.io). Read AboutDocumentation first.

Format

Having documentation in one large piece would make its structure too rigid. Maintenance and online navigation would be impractical. Instead, it's split into small pages. Therefore it doesn't exist in other formats. Offline viewing is easy in Firefox:

Run Jekyll locally.

SeLite doesn't use GitHub Wiki, which doesn't utilise screen well, especially on mobile devices. (E.g. its sidebar has a wide mandatory part).

Maintaining the documentation

  • See Github-flavoured Markdown, Liquid for Designers and Kramdown syntax.
  • Write and organise it clearly.
  • Provide examples.
  • Don't have any content before the first heading (# Heading... #).
  • If a heading contains any special characters (e.g. <, >), then specify its ID on the next line in form {:#heading-id-here}.
  • Refer to third party documentation if you mention something for the first time (if you have a reference).
  • Try NetBeans. See DevelopmentTools > NetBeans as a Javascript IDE. Install Markdown support. Open the documentation folder as a PHP project.
  • Don't use fixed line length, especially not in documentation source.
    • A good IDE/editor should be capable of wrapping lines. Take benefit from all your available screen area and don't worry about line lengths.
    • Reasonably long lines make source search and narrowing down easier. Search results preview containing long enough lines may be enough for you to know that you can skip the occurrence, without opening that line in editor.
    • You need long lines for pre-formatted text, such as code blocks and Drawn diagrams.
    • In NetBeans choose menu Tools > Options > Editor > Formatting > Line Wraps: After words.
    • If you need Eclipse, try http://dev.cdhq.de/eclipse/word-wrap/ (install both components: word wrap and line numbering fix); however, line numbering fix (for Eclipse Kepler) doesn’t work in Eclipse Luna (4.4).
  • Format any chrome:// URLs in italic but don't make them links. See AboutDocumentation > Firefox {{chromeUrl}}s.
  • Don't have blank lines in HTML comments in .md files. Such comments work well online, but not with Markdown Viewer in Firefox.
  • Don't blindly rely on Markdown support for NetBeans, neither on Markdown Viewer for Firefox.
  • Don't have links in headers - otherwise they are confusing in TOC. See also gettalong/kramdown#252.
  • Preview by running Jekyll locally: bundle exec jekyll serve. The default port is 4000 (the local website at http://localhost:4000). Alternatively pass a port, e.g. bundle exec jekyll serve --port 8000.
  • gem install link-checker and check-links _site (not maintained since v. 0.7.2, Oct 2012; it reports broken external links but not broken local links). Don't use html-proofer gem and its htmlproof command (since it doesn't like GitHub-based relative links).
  • Use online W3 Link Checker. A faster way: run it locally with Jekyll 3.0 (or with gem install jekyll --pre):
    wget http://search.cpan.org/CPAN/authors/id/S/SC/SCOP/W3C-LinkChecker-4.81.tar.gz
    sudo cpan -i Config::General Net::IP CSS::DOM
    tar xvzf W3C-LinkChecker-4.81.tar.gz; cd W3C-LinkChecker-4.81; perl Makefile.PL; make; sudo make install
    checklink --quiet --location http://localhost:4000/ http://localhost:4000/

Drawn diagrams

Don't use UML tools, as they are more restrictive and less efficient.

Draw diagrams in LibreOffice/OpenOffice and save them as .odg. Then Edit > Select All; File > Export (export the selection, rather than the whole drawing area). Export as a .png, not interlaced, with lowest compression. Then commit both .odg and .png to git. In documentation use URLs of 'Raw' images from git (e.g. selite/diagrams/ > navigate to .png file > get URL of 'Raw' button).

Versions of LibreOffice

  • LibreOffice version that came with CentOS 6.4 didn't export as .png well - the quality was low.
  • CentOS 6.5 has LibreOffice 4.0.4.2, which is better than one from CentOS 6.4, but it still doesn't export very well.
  • LibreOffice 4.1.3.2 that came with Fedora 19 KDE worked well.
  • Fedora 20 KDE has LibreOffice 4.1.4.2, which renders well.

Please

Textual object diagrams

Object Diagrams draw ownership/reference relationships between objects, fields and functions. They usually don't necessarily describe class inheritance (which is clear from the source and from [API]).

Text diagrams don't need to be esthetic, but clear and easy to edit - so you can quickly update them whenever you change the relevant code. They are in plain text, with <, >, ^, v for connections. The diagrams look like this:

Example                                     Description

ObjectConstructorName                       Full name of the class - i.e. the constructor function of the object.
Below the object constructor name are object fields. Indent them with two spaces.

.fieldName                                  Field with a fixed (known) name. Prefix it with a dot.

[ index description or expression ]         Dynamic field name.

[ ObjectConstructorName.SECRET_FIELD_NAME ] Field with a fixed name, not referred to via a string/numeric literal across the code,
but rather as a value of a defined constant.

Headers IDs must be the same as their text

Don't use Kramdown-specific header IDs, since they don't work in Markdown Viewer in Firefox..

Raw content from GitHub

GitHub doesn't serve raw versions of most file types with their MIME, except for images.

  • Use htmlpreview.github.io only for displaying .html files (but not for processing them programatically). It fetches the latest commit of that file. Therefore you don't have to update those links (unless you move the file).
  • For any other files (e.g. .xml, .xsl or .js), and for processing .html files programatically, use rawgit.com
    • only development only use https://rawgit.com -based URLs. They fetch the latest commit.
    • in production use https://cdn.rawgit.com -based URLs. They are cached. Hence (re)generate a unique link for the commit you need. See below. Then update any existing links.
  • Don't use raw.githubusercontent.com, because it doesn't serve the right MIME type (SEC7112 - 'blocked due to mime type mismatch').

Generating cdn.rawgit.com-based URLs

The most difficult part is to locate the 'Raw' link (on GitHub) for a chosen commit.

The URL will start with https://raw.githubusercontent.com/. Copy the URL. Paste it at https://rawgit.com. Take the url starting with https://cdn.rawgit.com.

For example, the 'Rw' URL is_https://raw.githubusercontent.com/selite/selite/XYZ.../\<component's-name>/src/chrome/..._ Then append the path part of that URL to https://cdn.rawgit.com/, i.e. https://cdn.rawgit.com/selite/selite/XYZ.../\<component's-name>/src/chrome/...

Apply similar steps to SelBlocksGlobal.