🐬
SA Metadata Creation Guide draft
  • Introduction
  • Roles & Responsibilities (draft)
  • Goals of SA Data Management
  • SA Science Metadata Catalog
  • Projects, Products, Contacts
  • Non Duplication Policy Guidance
  • Workflow
    • Metadata From Scratch
    • Metadata From ScienceBase
    • Metadata Editing / Re-Publishing
    • PTS Considerations
  • Settings
  • mdEditor Metadata File Management
    • Import
      • mdJSON
      • sbJSON
      • FGDC
    • Export
    • Copy Records
  • Metadata Requirements Checklist
  • Digital Object Identifier (DOI)
  • Project Entry Guidance
    • Main Tab: Project
    • Metadata Tab: Project
    • Keywords Tab: Project
    • Taxonomy Tab: Project
    • Extent Tab: Project
    • Documents Tab: Project
    • Funding Tab: Project
    • Associating Records: Project
  • Product Entry Guidance
    • Main Tab: Product
    • Metadata Tab: Product
      • data.gov Guidance
    • Keywords Tab: Product
    • Taxonomy Tab: Product
    • Extent Tab: Product
    • Lineage Tab: Product
    • Distribution Tab: Product
    • Constraints Tab: Product
    • Dictionaries Tab: Product
    • Documents Tab: Product
    • Associating Records: Product
  • Co-funded Project Requirements
    • Collaboration Protocol
    • Sub-Project Protocol
      • Sub-project of FWS Region or Program Project
      • Sub-project of CASC Project
    • Co-funded Protocol
      • FWS co-funded Projects
      • FWS/CASC Projects & Products
      • CASC Responsibilities
      • LCC Examples
  • Contact Entry Guidance
    • Summary Contact Requirements
    • Individual Contacts
    • Organization Contacts
  • Publish
    • Requirements for Publishing
    • Testing Publishing
    • How to Publish
    • Re-Publishing
  • Archiving Requirements
  • Trouble-shooting Tips
    • QA/QC Fixes
      • QA/QC Resources
  • Bulk Editing Resources
    • Injector Script: Funding
    • Injector Script: Distribution Links
  • Help
  • Glossary of Terms
  • Documentation Guide
Powered by GitBook
On this page
  • About this guide
  • Who is this guide for?
  • What is it about?
  • Workflow
  • Setup Environment
  • Style Guide
  • Headings
  • Lists
  • Icons
  • Buttons
  • Hints
  • Screenshots

Was this helpful?

Documentation Guide

PreviousGlossary of Terms

Last updated 4 years ago

Was this helpful?

About this guide

Who is this guide for?

This guide is intended for parties interested in contributing to this documentation.

What is it about?

This guide describes a recommended workflow and required conventions to be used when creating content.

Workflow

Setup Environment

The following is required:

  • NodeJS (v4.0.0 and above is recommended)

  • git

  • Windows, Linux, Unix, or Mac OS X

  1. Install gitbook-cli using npm:

     $ npm install gitbook-cli -g
  2. Clone the mdEditor GitBook:

     $ git clone https://git.gitbook.com/cookmt/mdeditor-for-lccs.git
  3. Setup GitBook

     $ cd mdEditor-for-lccs
     $ gitbook install
  4. Start the local GitBook server

     $ gitbook serve

Style Guide

This section covers styling conventions required for this documentations. Some of the conventions rely on plug-ins that enhance the native GitBook Markdown functionality. In some instances, the effects of the plugins are not displayed until after the book has been generated.

Headings

Please use headings to define page sections. Heading levels should appear sequentially without gaps (don't skip heading levels). Headings should start at Level 1 for the page title. Headings should not be used purely to define font styles - if absolutely necessary, use CSS for that. Following this convention will make it possible to parse the markdown programmatically, e.g. to dynamically create a table of contents.

Lists

Ordered lists

Ordered lists are processed irrespective of the actual number assigned to each list item. For Example:

1. first
2. second
3. third
  1. first

  2. second

  3. third

is rendered the same as:

1. first
12. twelfth
30. thirtieth
  1. first

  2. twelfth

  3. thirtieth

Therefore, one recommended convention is to use 1. for every item in an ordered list. This makes it easier to insert or remove items from the list, at the expense of slightly less readable Markdown. If you choose to sequentially order the list items, you must make sure the numbers are sequential to avoid confusion.

List headings

Headings may be use in lists. However, special handling is required to ensure bullets for ordered lists are styled appropriately.

The tasks tag is available for styling "task lists". For simplicity, all of the various heading levels are styled the same.

Example without task tag

1. ## Level 2
1. ### Level 3
1. ###### Level 6

Example without task tag

  1. Level 2

  2. Level 3

  3. Level 6

Example with task tag

<!-- tasks -->
1. ## Level 2
1. ### Level 3
1. ###### Level 6
<!-- endtasks -->

Example with task tag

  1. Level 2

  2. Level 3

  3. Level 6

Icons

<i class="fa fa-smile-o"> </i> Happy Birthday <i class="fa fa-birthday-cake"></i>

Happy Birthday

Buttons

Default Primary Success Info Extra - Small Warning - Small Danger - Large Link

<!-- Standard button -->
<span class="btn btn-default">Default</span>

<!-- Provides extra visual weight and identifies the primary action in a set of buttons -->
<span class="btn btn-primary">Primary</span>

<!-- Indicates a successful or positive action -->
<span class="btn btn-success"><i class="fa fa-check"></i> Success</span>

<!-- Contextual button for informational alert messages -->
<span class="btn btn-info btn-xs">Info Extra - Small</span>

<!-- Indicates caution should be taken with this action -->
<span class="btn btn-warning btn-sm">Warning - Small</span>

<!-- Indicates a dangerous or potentially negative action -->
<span class="btn btn-danger btn-lg">Danger - Large</span>

<!-- Deemphasize a button by making it look like a link while maintaining button behavior -->
<span class="btn btn-link">Link</span>

Hints

Styled hint blocks are supported.

{% hint style='info' %}
Important info: this note needs to be highlighted
{% endhint %}

There are five supported variations.

  • info (default)

  • tip

  • danger

  • working

  • plain

Info: this note needs to be highlighted.

Tip: 20% is customary.

Danger: this is going to blow up!

Working: for the man every night and day...

Plain: booooooorrrrring.

Screenshots

The following software is required:

  • A tool to capture screenshots

  • Windows, Linux, Unix, or Mac OS X

Types of screenshots

  1. basic screenshots have no annotation or markup applied

  2. annotated screenshots have markup applied, e.g. callouts, highlights, etc.

Requirements for all screenshots

  1. Minimum 1200px wide

  2. Must include a caption

  3. PNG format

  4. Images should be stored in the assets directory corresponding to the section in which the image appears. Exceptions to this requirement are made for images used in multiple sections.

  5. Image sizes should be as small as possible without sacrificing quality.

    Usually significant size reduction can be achieved by color-type or bit-depth

Requirements for annotated screenshots

  1. Use LibreOffice Draw to create the annotations

    • A template is available here /assets/documentation-guide/callouts-template.odg

    • Each screenshot should be placed on a new page

    • Whenever possible place annotations in callouts outside of the image or

      in a way that does not cover user interface elements

    • Name the page using the name of the PNG file

    • Export the screenshot to PNG

      • only export the

      • compression level 6

      • 1200 pixels wide

  2. All annotated screenshots for a section should be stored in a single .odg file.

  3. Save the LibreOffice Draw file (.odg) in the directory with the screenshots

Screenshot captions

To apply a caption to a screenshot use this syntax in the Markdown.

![caption goes here](/assets/path/to/image){caption}

To apply a border to a screenshot, add class=border.

![caption goes here](/assets/path/to/image){caption class=border}

Applying the {caption} to a image will also indent the image from the surrounding text.

Bookmarlet for Screenshots

javascript:(function(){var windowObjectReference;var strWindowFeatures='menubar=no,location=yes,resizable=yes,scrollbars=yes,status=no,width=1200,height=1200';windowObjectReference=window.open(window.location.href,'Plain Window',strWindowFeatures);})();

While the online editor may be used, the most efficient way to create documentation is to install the GitBook Toolchain locally. See for detailed instructions. The short version follows.

A Markdown editor/IDE ( is a good open source choice)

Open a browser to:

icons are available. Use an <i> tag to render the chosen icon.

style buttons are supported. Use a <span> tag since these are for documentation only. Icons may be combined with buttons.

Generally browser window captures should only contain minimum user interface controls, without navigation toolbar, tab bar, bookmarks toolbar, or status bar. See .

{caption class=border}

reduction. is a good tool for this.

{caption class=border}

{caption}

{caption class=border}

Use this bookmarlet: Plain Window. Drag the link to your bookmarks bar or create a bookmark with the code below. Clicking the bookmark will open the current webpage in a plain window that is 1200px wide. Re-size to needed height and take a screenshot. More about bookmarlets here: .

https://toolchain.gitbook.com/
ATOM
http://localhost:4000
FontAwesome
Bootstrap 3
Libre Office Draw
pngcrush
https://www.wikipedia.org/wiki/Bookmarklet
About this guide
Who is this guide for?
What is it about?
Workflow
Setup Environment
Style Guide
Headings
Lists
Ordered lists
List headings
Icons
Buttons
Hints
Screenshots
Types of screenshots
Requirements for all screenshots
Requirements for annotated screenshots
Screenshot captions
Bookmarlet for Screenshots
Bookmarlet for Screenshots
Creating screenshots using LibreOffice Draw
Example browser screenshot.
Screenshot with border
Screenshot with caption