/
Infusion Documentation Style Guide
Infusion Documentation Style Guide
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 narrative paragraphs, tables, etc.
- DO NOT use code styling in headings; this will break links to the heading anchors.
- 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 theinfusion-docs-note
class and begin with "Note:"; This will ensure that the note is styled according to the designs.
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?
, multiple selections available,
Related content
Infusion Documentation Plan
Infusion Documentation Plan
More like this
Infusion Documentation Architecture and Process
Infusion Documentation Architecture and Process
More like this
Infusion Documentation Testing April 15, 2015
Infusion Documentation Testing April 15, 2015
More like this
Fluid Infusion 1.4
Fluid Infusion 1.4
More like this
infusion-1.0-has-been-released
infusion-1.0-has-been-released
More like this
Embedded Infusion license
Embedded Infusion license
More like this