Begin style guide: Document conventions

[joshix]

Add a style/ directory.
Add STYLE.md guide to conventions and standards. Beginning with headings.

Addresses https://github.com/coreos-inc/coreos-pages/issues/324

[robszumski]

I wasn't sure what to make of this at first. Maybe we have an example that uses the headings in the doc as an example and it looks something like:

For example, this document's headings are structured in code as:

# Headings in CoreOS Documentation

## Documentation Format

### Subheadings

#### Subheadings and the Sidebar Outline

### Example: *The "Average" Document*

[robszumski]

Should we go ahead and make the whole styleguide one document, ie styleguide.md and keep it in the root dir, like the license, etc?

As much as I hate to suggest this, maybe do all caps like the rest, ie STYLEGUIDE.md

[robszumski]

We can always break it apart later if needed

[jonboulle]

This is inconsistent with the preceding line

[jonboulle]

Perhaps not in this PR but would love to address the wrapping issue raised in rkt/rkt#1648. Generally speaking, we've tried to stick to a "one sentence per line" policy in markdown documentation because it makes it much easier to review diffs on GitHub.

[robszumski]

@jonboulle I break this rule all over the place, so we should try to figure out a rule around that.

[jonboulle]

dragging in @philips ...

[joshix]

@robszumski Re: file names/directory anticipation: I'm so much in the undecided column that I started on two previous drafts with the file name styleguide.md, then STYLEGUIDE.md in observance of observed local custom. However I moved it into a directory because then each file beneath style/ may have a shorter name and this particular iteration can omit an introduction explaining it is not in fact the Style Guide, etc. This to explain my thinking, rather than argue with urgency for either side.

I had thought about some more-developed later version living in a file named coreos/docs/CONTRIBUTING.md, superseding this PR, following the model of, and linked to from within, existing code contribution guidelines like https://github.com/coreos/etcd/blob/master/CONTRIBUTING.md.

[joshix]

@jonboulle So the source for markdown would look like:

# Markdown line breaks

This is a sample document showing the proposed one-sentence-per-line formatting convention.
This second sentence continues the same paragraph.

This third sentence begins a second paragraph.

## Second heading

This sentence is short.
This sentence is longer.
This sentence is longest.

This sentence is lonely.

Renders as:

Markdown line breaks

This is a sample document showing the proposed one-sentence-per-line formatting convention.
This second sentence continues the same paragraph.

This third sentence begins a second paragraph.

Second heading

This sentence is short.
This sentence is longer.
This sentence is longest.

This sentence is lonely.

Other renderers ignore the single-LF and join lines so separated into paragraphs, but the github renderer seems to obey rather than ignore them.

[jonboulle]

I'm confused. We do this successfully elsewhere. Let me look when in front
of keyboard again.
On Oct 21, 2015 13:38, "Josh Wood" notifications@github.com wrote:

@jonboulle https://github.com/jonboulle So the source for markdown
would look like:

Markdown line breaks

This is a sample document showing the proposed one-sentence-per-line formatting convention.
This second sentence continues the same paragraph.

This third sentence begins a second paragraph.

Second heading

This sentence is short.
This sentence is longer.
This sentence is longest.

This sentence is lonely.

Renders as:
Markdown line breaks

This is a sample document showing the proposed one-sentence-per-line
formatting convention.
This second sentence continues the same paragraph.

This third sentence begins a second paragraph.
Second heading

This sentence is short.
This sentence is longer.
This sentence is longest.

This sentence is lonely.

Other renderers ignore the single-LF and join lines so separated into
paragraphs, but the github renderer seems to obey rather than ignore them.

—
Reply to this email directly or view it on GitHub
#633 (comment).

[joshix]

I think the github md interpreter gives different output here in a comments chain vs on displaying a source file, e.g., coreos/docs/README.md. That file when experimentally adjusted toward one-sentence-per-file-line displays as expected, with single LF usually just consumed and ignored. See joshix@81debe7

One-sentence-per-line:

Pro:

• Definitely easier to diff and review.

Con:

• More tedious to write
• More tedious to read as source and/or in terminal
• Does not address 80-char width also discussed in related issue(s)

[jonboulle]

I'm still in favour of optimising for diff reviews, and am not really concerned about the tediousness of writing it.
Crazy compromise: 80-char width but new sentence always means newline?!

[crawford]

I don't really like the idea of imposing this restriction on all teams just because some most teams use poor tooling to review diffs (read GitHub (which still blows my mind)). I'm in favor of an 80-char limit (without the proposed line break) since I get work done in a terminal and that is where the docs need to be readable.

[jonboulle]

@joshix care to make an executive decision on this one?

[joshix]

Sure. Let me hang the exit sign on the bikeshed door:

1. One-sentence-per-line: Nice idea. But formatting concerns begin to tread on the ideas the reader is trying to understand, the writer is trying to communicate. The text becomes fussy and stops looking like paragraphs when read in markdown source form. The value added in reviewing is, to me, minimal. Write natural english sentences and paragraphs, not one-sentence-per-line.
2. Character per line limit: Obey projects' 80-char per line rule. URLs and other literal formations can break this rule for a line or two. Use common sense, but generally wrap your lines at around char 80 unless the wrapping newline breaks the output from the presentation layer.

I intend to write as much into the CONTRIBUTING guide and update this PR, unless anyone thinks I should be set on fire instead.

Cf. https://github.com/google/styleguide/blob/gh-pages/docguide/style.md#character-line-limit

[jonboulle]

Markdown compiler is the source of truth.

I don't follow, source of truth for what?

[joshix]

Just about whether or not something can or cannot be line-wrapped.

[jonboulle]

SGTM, probably best to get an ack from @philips as AIUI he's the initiator
of the one-sentence-per-line style

On Wed, Nov 18, 2015 at 1:14 PM, Josh Wood notifications@github.com wrote:

Just about whether or not something can or cannot be line-wrapped.

—
Reply to this email directly or view it on GitHub
#633 (comment).

[philips]

I still like one sentence per line and it works in nearly all editors. The 80 char rule gets you into doc churn hell because everyone's editor is going to do something different whether that be wrapping to 79, wrapping words with dashes, etc.

[joshix]

@philips Since we don't agree, let me spell out my reasoning and you can make the ruling. I thought about the points you raise, but I came down to two points: 1) as @crawford alludes, part of the intent of Markdown is plain-text readability. The source document is supposed to be a fair rough representation of the document as rendered. We write the kind of docs with markdown that one would expect to read in a terminal. The one sentence-per-line rule makes this pretty terrible. Nothing looks like a paragraph. I presumed (not knowing the history) that markdown was chosen for these conventional reasons and therefore those goals were worth preserving.

Having thought it out that way, I compared with some style guides for large repos using Markdown. Google's rules pretty much encapsulate what I was aiming for. Maybe that's confirmation bias. https://github.com/google/styleguide/blob/gh-pages/docguide/style.md#character-line-limit

In order, I would happily concede on the proposed 80-chars per line. I truly think the intent of markdown is writing natural english paragraphs, and I kind of hate humanfmt in general.

I would be forced to concede, but like it much less, if we had to adopt one-sentence-per-line all over.

[joshix]

Note: spec unordered list style (* Item)

[jonboulle]

I should clarify that my preference is not strictly sentence-per-line, but rather just avoiding line length limits. I'm +1 on the proposed paragraph-per-line.

[joshix]

YAML files: secret.yaml vs secret.yml

Set style for this. Before deciding, note that upstream k8s tends to say *.yaml.

[joshix]

@robszumski @meghanschofield @philips I think we could land this as a delightful holiday gift for one and all. Would enjoy your parting thoughts on same.

[robszumski]

yes yes yes. I hate saying "these are available here"

[jonboulle]

shakes fist

[robszumski]

Added a few comments, but overall looks good.

[jonboulle]

GitHub