Guidelines - merb-book | Google Groups

Proposed

Approved

Inline Code Examples

Code examples should have their first character indented 4 spaces (not tabs), with any additional indentation following the Ruby standard of 2 spaces (again, no tabs). The reason the first character should be indented 4 spaces is that Markdown will put these lines inside of <pre><code> blocks. On the line immediately following the last line in the example, add this (with no indentation):

{:lang=ruby html_use_syntax=true}

This will instruct Markdown to add CSS classes to give the code pretty syntax highlighting. For example:

    def greet_visitor(visitor_name)
      "Hi #{visitor_name}!"
    end
{:lang=ruby html_use_syntax=true}

If you need further examples, take a look at "/book-content/en/1-introduction/1-ruby.markdown".

Line breaks

This guideline covers the formatting of the Markdown source code for "normal" paragraphs:

Each sentence should begin on a new line.
Additional line breaks should be added as needed to keep lines under 80 characters. Ideally, these should be placed between clauses, etc.

There are several reasons for these guidelines:

It's easier to see the structure of the narrative, because each sentence is seen as a "chunk".
It's easier to move sentences around, because selecting a line or two is much faster and easier (see Fitt's Law) than selecting an arbitrary sequence of characters.
It's easier to merge changes, because only the changed sentences need to be considered (as opposed to the entire paragraph).

For example, here is a soft-wrapped (non-compliant) paragraph:

merb-gen app

And here is the hard-wrapped (compliant) version:

merb-gen app

Quoted paragraphs can also be broken by putting '>' at the start of each line:

Note: Do not allow any trailing whitespace at the end of lines; they will cause line breaks!

There is a helpful Rake task which will print the files (with line numbers) containing trailing whitespace. It is recommended that you use this task before making your commit to ensure that the committed files are clean and will be rendered properly. Usage is simple:

$ rake whitespace

Link Definition and Use

This guideline covers the definition and use of links:

Use Markdown's "implicit" link format.
Define the links at the end of each file, nicely formatted and sorted (eg, alphabetically by name).

The rationale for this guideline is that explicit links are typically too long to fit well in 80-column lines. In addition, the URLs break up the material, making it hard to read. Finally, the implicit format reads more nicely than the explicit format. So, here is an example:

So, [Matthew Ford][] decided to work on an [Open Source][] book
with a simple goal:
help courageous Rubyists who wanted to live on the edge
and had decided to try Merb, [DataMapper][], and [RSpec][].
...
[DataMapper]:       http://datamapper.org/doku.php
[Matthew Ford]:     http://github.com/deimos1986
[RSpec]:            http://rspec.info

List definition

Ordered lists should use lazy numbering, starting from one, as per Markdown recommendation:

If you do use lazy list numbering, however, you should still start the list with the number 1. At some point in the future, Markdown may support starting ordered lists at an arbitrary number.

Nested lists should be indented with two spaces. For example:

1. [Front Matter](/front-matter)
  1. [Foreword By Yehuda Katz](/front-matter/foreword)
  1. [Preface by Matt Aimonetti](/front-matter/preface)
  1. [Contributors](/front-matter/contributors)
1. [Introduction](/introduction)

Size Limits

This guideline covers the suggested sizes for sentences, paragraphs, and sections:

Any sentence that contains more than ten words should be regarded with suspicion.
Any paragraph that contains more than four sentences should be regarded with suspicion.
Any section that contains more than four paragraphs should be regarded with suspicion.

The rationale for this guideline is that long sentences and paragraphs are harder to digest and long sections provide little navigational assistance to the user. In addition, as sentences get longer, they become more difficult to construct and punctuate.

Note: These are not hard limits; rather, they are "test smells" (ie, reasons to inspect the text for possible problems).

Translations

Each translation should have its own branch on mattetti's GitHub repo. Each language leader can push directly to his branch.

Once a week, the language leader will rebase his branch on master and merge it into master. If the language leader is not comfortable with that, please contact mattetti.

Translations should follow the guidelines defined on this page.

Version: