Proposed Guidelines:
Infusion documentation is written using Markdown and then converted to HTML using Docpad. The source files and templates are stored in github: https://github.com/fluid-project/infusion-docs/
Editorial
- Any references to grade names, parameter names, function names, etc. should be
styled as code
, for example, usefluid.defaults
and not fluid.defaults.- This applies inside headers, narrative paragraphs, tables, etc.
- References to HTML elements should be styled as code and wrapped in
< >
, for example, a<div>
element. - Section headings should use sentence-style capitalization (only capitalize the first word and proper nouns) rather than headline-style capitalization.
- Code snippets should use line breaks judiciously, to improve readability and avoid horizontal scrolling.
Page structure
- Pages should begin with introductory paragraph(s) without any
<h2>
level header. Subsequent sections should begin with<h2>
headers.- The page title, specified in the metadata of the Markdown file, will be converted to an
<h1>
header ahead of the introductory content.
- The page title, specified in the metadata of the Markdown file, will be converted to an
- Any text that will be consistent across a number of pages (e.g. production status notes or deprecation warnings) should NOT be hard-coded into the Markdown. Instead, use metadata that will be processed by Docpad, to ensure consistent wordings.
- The specific mechanism for this will be determined when it needs to be implemented.
- "Notes" should be wrapped in
<div>
elements with a specific class to be used for styling according to the designs. The class name is yet to be determined.
Questions
- Should text in a header be styled as code? It makes detecting a header a little bit difficult.
- Should this style guide live inside the github repository with the source files, or here in the Fluid wiki space?