Style guide

[joeyaiello]

There's currently some inconsistencies in the way Markdown is authored in this repository, but we should coalesce on a single style guide, including guidance for:

• indentation
• • vs _
• extra carriage returns (e.g. underneath headers, when a line gets too long, etc.)
• when to use bold, italic, code highlighting, etc.

[joeyaiello]

One of the first orders of business should be insert an extra line break after each sentence to ensure that console diffs look reasonable.

[nzubair]

This can use some love. Would it be possible to establish at least a basic style guide for new contributors? Instead of relying on folks to look around, notice conventions, and make judgement calls.

Issues currently open regarding style:

#1039
#1038
#1025
#1018

[nzubair]

A quick write up about a few style elements when working with PowerShell documentation.

I've added it as a gist because some of the formatting, e.g. paragraphs, etc, seemed to be handled differently in issues/comments vs. in .md files:

https://gist.github.com/nzubair/d7b106994cb85a66909e06a509020855

/cc @zjalexander @HemantMahawar @joeyaiello @juanpablojofre

[joeyaiello]

@nzubair: you're absolutely right, we really need to do something here. I'm cleaning up an about_topic right now, and I have way too many open questions about how I should format things.

Thanks for writing up that gist. I actually have a branch from a million years ago where I did something similar: https://github.com/PowerShell/PowerShell-Docs/blob/styleGuide/STYLE.md

If @juanpablojofre, @eslesar, @zjalexander, and @HemantMahawar agree, we should probably merge elements of your gist into that document as we close on them in various issues.

[zjalexander]

a bunch of people are out on vacation right now, but this is on the top of my list for documentation issues. I'll start drafting some stuff but I won't be able to review it with the right people for another week.

[nzubair]

sounds good :-)

[zjalexander]

ok, ./styleguide.md now exists . please feel free to comment, discuss, submit PRs to change stuff, etc.

[exchange12rocks]

What if we adopt common capitalization rules for this project? I.e.:

• Do Capitalize
  • Nouns (file, cmdlet, object)
  • Adjectives (small, fast, executable)
  • Verbs (update, connect, delete)
  • Adverbs (slowly, quickly, quietly)
  • Pronouns (he, she, it)
  • Subordinating conjunctions (as, because, that)
• Do Not Capitalize
  • Articles: a, an, the
  • Coordinating Conjunctions: and, but, or, for, nor, etc.
  • Prepositions (fewer than five letters): on, at, to, from, by, etc.

Otherwise, I am forced to format titles like this (currently only the first letter in a first word and in nouns should be capitalized): How to update Help Files in different Languages, How to support updatable Help.

[sdwheeler]

@exchange12rocks Microsoft style is sentence-style capitalization. That means everything is lowercase except the first word and proper nouns, which include the names of brands, products, and services. See https://docs.microsoft.com/en-us/style-guide/capitalization

[sdwheeler]

CommonMark is the official specification for markdown syntax. We need to update the style guide to give more specific guidance.