Content Style Guide and Workflow

Purpose

Audience: iDigBio content creators (Wiki, Drupal, and Redmine)

The following are guidelines to help you make consistent, findable documents. They do not constitute a full and inclusive style guide, but seek to help you understand and use the system. They support the 2013 Wakulla web presence design. Be aware that there is a detailed workflow that goes along with the lifecycle of creating and publishing some of the content in this guide, e.g., calendar events, workshop wikis, agenda, videos, biblio records. It is in progress and will be provided later.

Support

Anyone wanting support for their Drupal or Redmine accounts should write a Redmine ticket: https://redmine.idigbio.org/

iDigBio sources of content

iDigBio uses multiple technologies to create and track content: Drupal (including Forums and Biblio), Wiki, Redmine, and further down the line of rich content, listservs. This document covers just the first two in depth.

Drupal: A content management web application system that provides infrastructure for content providers: website style templates, document templates, document storage, user privileges to name a few. Access to Drupal is limited to iDigBio staff. See a list of content types (templates) below.
Wiki (Media Wiki): Another kind of content management system that has a more open architecture, and more rudimentary tools than Drupal. It provides a familiar interface to anyone who has used Wikipedia, and also document storage for a more limited number of MIME types. It is open to all iDigBio users with a logID. This fact makes it susceptible to spammers who create bogus content, sometimes in hard to find places.
Drupal Forums: These were created at the beginning of the project for community interaction without requiring our input, on topics related to our mission. They have not been used much in the last year.
Drupal Biblio: These are a special kind of Drupal document for creating a searchable record of all of our workshop artifacts, e.g., presentations, videos, posters, and other media.
Redmine: A flexible project support web application that is used for tracking features, bugs, and critical internal project documents.
listserv: These are created to support easy email interaction between members of working and interest groups (like these), and among the various kind of project management groups (TCNs, PIs, Steering Committee, EAB, IAC).

Drupal content types

There are several ways to provide content in Drupal. Content templates have been created for our use. The ones below are the most frequently used. For the complete list see Drupal content templates. If you have any doubts about how to use which template, or when, look in the repository at some examples.

Article: Use for time-sensitive content like news, press releases or blog posts. You can also use articles to create employment postings: be sure to include an expiration date and the tag "Employment"; you may also want to use the tag "Press Releases" so that the job posting aggregates in the News feed.
Basic page: Use basic pages for your static content, such as an 'About us' page.
Biblio: Use for scholarly content, such as journal papers and books, as well as our workshop media.
Community Announcements: Use this content type to tell the iDigBio community about upcoming events, projects or other items pertinent to biodiversity and biological collections.
Forum topic: A forum topic starts a new discussion thread within a forum.
Press Release: Use this to issue press releases and re-publish existing press releases issued via other organizations.
Service Affecting Events: Use this to create calendar events that affect iDigBio's services. You can use this content type to document service affecting maintenance of systems, interruptions to production and beta services, known third-party hosting outages, etc. You must include start/end dates/times and affected services. Entries will be added to the calendar and a notice will be displayed on the iDigBio.org homepage the week of the event.
Webform: Use this to create a new form or questionnaire accessible to users. Submission results and statistics are recorded and accessible to privileged users.

Suggested style elements

Where possible or applicable, documents should have these meta-style elements, in order of preference, for ease of understanding the point of view of the document.

tags (called 'categories' in Wiki terminology)
audience
version
date

Redmine organization

Redmine is organized into projects: https://www.idigbio.org/redmine/projects Currently, there are 5 major projects, representing the areas of the 5 PIs in the project. Each project has its own set of tickets, files and documents, and wiki pages. Most of active wiki pages are in the "Website" project (https://www.idigbio.org/redmine/projects/website/wiki) and contain minutes of various types of meetings (steering committee, IAC, UF/FSU IT, ACIS IT), logistic information on workshops, contact lists, cyberinfrastructure organization, drafts of documents for end-users and so on. Anyone in iDigBio can submit a ticket reporting problems with the website or portal, new activities, requirements, risks and feature requests. The tickets are to be separated by project. For example, a bug found in the website should be submitted to the "Website" project. In the case of data ingestion tickets, there is a known documented workflow.

When to use Wiki

Wiki content is by default always published. It is intended to be a means for collaboration among colleagues on staff and within the biodiversity community. It is a also a tool to work on a draft with a group before committing it to a PDF in Drupal. Supporting documents can be uploaded, but for security, are restricted to MIME types that do not pose a potential threat, e.g., Word files, Excel files, PDF, PNG, GIF, JPG. Refer to a list of supported upload file types

When to use Drupal

Drupal documents are not likely to be as collaborative in nature once they are published. They are meeting reports, workshop reports, policy, webforms, announcements.

iDigBio staff and named working groups or participants may upload files via the file browser at https://www.idigbio.org/imce The only restrictions on this space are the physical limitations of our servers and file system.

There are directories for workshop presentations and workshop images. Navigate to "workshop-presentations" or "workshop-images' and then to your file folder of interest. Use the "Upload" tool at the top of the screen to place files. If not already there, create a folder for the workshop of interest, make the name unambiguous.

Linking to files is easy. Highlight the file you just uploaded by clicking on it. At the bottom of the file browser window you should see "File URL path". Copy this and place "www.idigbio.org" in front of it, and you have a valid URL to this file.

When to use Redmine

Redmine is to be used for iDigBio internal documentation and tracking of ongoing activities at ACIS, FLMNH, and FSU, i.e., documentation in Redmine is only for internal consumption, and the ticketing system is to help track the progress of the project. If you are reporting a feature request or bug on behalf of an external user, please add all the details of the request, including the contact information for the user. Once tickets are submitted, they are assigned to the appropriate person. Internal documentation on how to submit a ticket via e-mail is documented here.

News

This is another view of certain kinds of Drupal documents based on their tags. Tagging something with 'Blog' makes it show up in the 'New Articles' column here: https://www.idigbio.org/news

When to make a Drupal Biblio entry

Biblio entries are used to record iDigBio's body of knowledge, which includes items such as published articles, workshop presentations, workshop recordings, etc. A Biblio record should be created for each piece of new content, including revisions to existing documents. To create a Biblio entry: https://www.idigbio.org/#overlay=node/add/biblio

When to use Forums

The Forums have been removed as of 06/2015 for lack of use. ~~Forums are a place for the ADBC community to discuss issues about biodiversity-oriented software, workflows, technology, standards, etc. Their activity ebbs and flows depending on the subject.~~

Linking to content - Wiki

Attention needs to be paid to representing links to content to make the link work, and to not show up on a wayward content report. The syntax of making a pretty-printed link, with the URL behind it sometimes takes a '|', and sometimes needs an extra space.

[https://www.idigbio.org/documentation documentation]

Use this format when linking to a piece of content in the iDigBio Drupal content space that is not a Wiki page, one set of square brackets, no '|'.

[[Content_Style_Guide_and_Workflow#When_to_use_Drupal|style guide]]

Use this format to link to Wiki content within your current document.

[[Media:Downtown_and_Gaines_St._dining.pdf|Map of downtown and Gaines Street dining options]]

Use this format when linking to a file that has been uploaded to the Wiki, e.g., a PDF, and you want to display the contents. Note the double, no space square braces, and the pipe sign between the link and the text of the title you want to show up in the URL.

[http://nature.berkeley.edu/tsutsuilab/SuarezTsutsui2004Biosci.pdf The Value of Museum Collections for Research and Society]

Use this format when linking to a resource somewhere else on the Internet.

[Accessing your Symbiota node and entering data]

Use this syntax when you are linking to another Wiki page, in this case "Accessing your Symbiota node and entering data" at the root level of the iDigBio Wiki.

Linking to content - Drupal

Link to external content in the usual way, with a fully expressed URL. If you wish to link to content that is in the Drupal 'File browser', see instructions elsewhere in this style guide how to retrieve the full path.

Editing content

The Wiki and Drupal use different markup for their content, although both are somewhat related to the familiar HTML, the Wiki less so. Help is available:

Editing content - Drupal

It is not recommended to include more than paragraph and line break markup in raw text of your document, and to avoid blanket copy/pasting from Word documents. The pasted text from Word includes a lot of unnecessary font treatment and style markup. Let your text follow the native Drupal style embedded in the website. Assistance in special formatting features like lists is possible via the 'Source' button in the content editor by letting you edit the markup inline.

Once you have perfected your document, reviewed it, tagged it, there are several key things to do to it to complete the workflow:

mark it Published if you are ready,
put the tag Featured into the tags field if you want it to appear in the carousel on the home page,
if you are putting it into the carousel, upload an image to display in it, even if you have included the same image in the body of the document.

Note: the state of being 'Unpublished' does not prevent a document from being found via the iDigBio Google search box, since if it has ever been published, it is cached for an unknown amount of time.

Editing content - Drupal - Images

Because the Drupal file browser is more restricted by user, and thus more secure to the system, more MIME types are allowed to be uploaded there than to the Wiki.

Editing content - Wiki

The first place to look to learn about the markup is in Media Wiki intro to formatting and a larger trove of help for special needs MediaWiki Help Table help, List help and Images and other uploaded files help. It is recommended in the long run to use the native markup. There is a Sandbox feature to help you get started with Wiki syntax. One efficient newcomer strategy is to find a page example you like in an existing page and copy it into your own document.

Creating content - Wiki

While a little obscure, the way to create a Wiki document is easy. Search for it, by the title you wish to give it, and then when you don't find it, click on the 'Create' button. Start creating content.

Editing content - Wiki - Images

To include an image in the flow of some text, upload the image (to Wiki for example) and insert this into the text, like this:

[[File:NameOfFile.gif|right|400px]]

The right parameter indicates placement in the text block and the 400px parameter scales it to fit to your taste.
Refer to a list of supported upload file types to avoid later diasppointments.

Images and image sizes

Images should be used to illustrate our activities, and be of the highest aesthetic quality as possible. Edit them for colour balance, exposure and alignment (straight to the horizon).
Convert camera images to jpg, 800px on the long side. If you are taking a picture for the carousel, keep in mind to leave extra space on the left edge as Drupal takes full advantage and often cuts off that side.
Verify that we have copyrights to images we did not originate (e.g., for posters, pamphlets).
Follow photographer practices of getting permission to use a person's likeness if we are the ones taking the picture. Exceptions apply to public places.

Writing style

The following topics *need to be defined*: what voice to use, what standard style manual to follow. There is some formative information documented at the beginning of the project, kept in Redmine: https://www.idigbio.org/redmine/projects/website/wiki/Editorial_Guidelines#section-8

When adding links, give preference to the HTTPS alternative (instead of HTTP).

Content tagging - Keywords

Our content tagging supports our website audience-based design (About, Portal, Technical Information, Education) by directing content to the right sub-sites; since not all content areas are fully-developed (e.g., Education), this sub-site feature is not completely fleshed out. Our tagging also supports how our design operates by assuring that content is searchable according to the existing Drupal custom-made views of the content. See Drupal tags below. Within each technology, i.e., Drupal, Wiki, at least one of the default tags should be used in each piece of content. The number of recommended tags will grow with need. Use tags that encapsulate the subject of your content, and don't to repeat the words in the title. Some rules of thumb for iDigBio tags:

Effort should be made to use the same universe of tags in both content systems.
No plurals, use the singular of a word or phrase, and don't repeat in the plural, e.g., Workshop, Workshops. An exception is allowed for nouns or phrases which are normally used in the plural or aggregate form.
Follow the case ruling set out by Wiki, i.e., leading upper-case a single word, lower case any following words in the phrase, e.g., 'Image ingestion'. Exceptions are allowed for titles, like Open Refine.
Separate things which have an ‘&’ or ‘and’ in them into separate tags, e.g., ‘Education & Outreach’, depending on context, this should be two tags: ‘Education’ ‘Outreach’.
A keyword should not repeat what is in the title, it should add to the range using synonyms that are easily recognizable. For example, in the following biblio documents:
- 'Intro to iDigBio' the keywords are: ADBC, digitization, documentation, Natural history collections
- 'Community Building: Collaboration & Opportunities' the keywords are: Summit 3
- 'iDigBio Imaging Equipment Recommendations' the keywords are: camera, copystand, lighting, software
Consider filling in 'Target Audience', as in 'Target audience: Digitization Specialists in Herbaria' in the Description field under keywords.
Use all that fit in each category (e.g., content, audience).

in Drupal

The following are a set of recommended content-related Drupal view-supported tags, choosing one for each piece of Drupal content will give it visibility under documentation:

Cyberinfrastructure
Data Ingestion
Database
Digitization
Documentation
Education
Outreach
Policy
Public Participation
Research
Workflow
Workshop

Special iDigBio Drupal tags:

Blog makes sure the content shows up on this page https://www.idigbio.org/news, under 'News Articles'
Featured puts the content into the carousel on the home page.

Put your tag(s) into the 'Tags' field when you 'Add Content', a comma-separated list. Let the system auto-match names if you are not sure.

in Wiki

Wiki tags are created with a syntax like

[[Category:tag]]

and can put anywhere in the content. If practical, put them at the top of the content so that they are easily found. Use general category tags or keywords that would be associated with the text.

Our current tag definitions are here https://www.idigbio.org/wiki/index.php/Special:Categories.

Reviewing

Every Drupal document should be reviewed by someone other than the original author prior to publishing.

Searching

There are numerous ways to search for content, and depending on which method you choose, the results will vary:

a plain Google search
a site specific Google search - returns content where the title or tags satisfy the search terms, but does not search PDFs
a site specific Wiki search - returns only Wiki pages whose content contains those words
using the Wiki Content by category search - returns documents strictly by the explicit category tags in the content.
using the browser find command (^f) search - returns only content on the current page

Note: none of the search strategies search within .pdf or .doc documents. This is one of the motivations to make tags useful for finding content.

Workflows for specific content types

iDigBio Standards

iDigBio Standards are document that reflect our policies.

Create a Basic Page for the document (e.g., "iDigBio Travel Policy"). Do this first, so it will be assigned a friendly URL.
- Tag the content as "Documentation" and/or "Policy" as appropriate
- You may also tag using subcategories, such as "Policy". See https://www.idigbio.org/documentation/documentation for current categories of documentation.
- In the Body, copy and paste the content from the document into the space provided. If you are copying and pasting from Word, make sure to delete all of the formatting tags that Word will insert into SPAN elements. You can click the Source button to view the HTML source.
- In the Standards Documentation box, choose the PDF version of the document and click Upload.
- Make sure to choose Published under Publishing Options at the bottom.
- Click Save.
For historical prurposes:
- Upload both the DOCX and PDF versions of the file into the internal-docs directory or idigbio-standards subdirectory as applicable.

iDigBio Events

Workshop, symposium, webinar, and other event content includes the PowerPoint presentations and multimedia recordings. Every individual workshop presentation should be uploaded as a PDF. Once the workshop and all the content has been added to the workshop Wiki, and the workshop is over, a Biblio record should be created for each piece of content. The Biblio entry is the end of the workflow that begins with an event (e.g., workshop, webinar).

An event begins with the Steering Committee, with a proposal (for workshops) for approval to spend funds. Once the idea, budget and schedule are approved by the committee, several documents are created, and a workflow is initiated. Note: not all events require this first step if no funds are required:

Before the event:
- the event is placed on the calendar (if critical or considerable planning has occurred, it may have been on the calendar already in a tentative state)
- an announcement is put into Drupal and emailed out to one or more of the listservs, and then linked to from the calendar event. If an additional Drupal page is developed beyond the simple announcement (e.g., more details, put into the carousel, etc.), then the announcement must link to it. [Note: the Outreach Event content type does not go to the carousel]
- a pre-evaluation may be scheduled - contact the project evaluator
- a Wiki page is created and linked from the calendar event
- a registration form may be put up, and linked from the Wiki and calendar event
- an agenda is created and linked from the Wiki and calendar event
- an Adobe Connect room is setup and linked from the Wiki and calendar event
- concurrently the logistics are developed as to the funding model, and relevant hotel blocks of rooms have been received (if applicable)
- the Wiki contains the agenda that accumulates links to uploaded presentations in PDF
During the event:
- the presentations are driven from the Wiki agenda
- Adobe Connect may be used to record the presentations
After the event:
- each presentation and recording is given a Biblio record
- a workshop report is written for the website and linked from the calendar event and the Wiki
- an evaluation of the event is performed

Miscellaneous content guidance

The following are ideas that will make managing documents in the long term easier.

File names
- Remove spaces in file names that will be uploaded and later linked to on the site, use either camelCase, or ‘_’ or ‘-’
- It is always a good idea to put the current version date into a file name, so that no one has to guess its currency. If you do, use the format year-month-day on the end of the name to support good sorting, e.g., documentName_20131004.
Documents should have a version or date in them, near the top, e.g., Version 1.0 2013-10-04
Use a byline if you feel comfortable doing so
Introduce the document with a header about who the audience is - this is especially helpful for our E&O directions, e.g., general audience versus technical.

Wayward content

There are several ways we keep track of wayward content:

Wiki Orphaned Pages Report: https://www.idigbio.org/wiki/index.php/Special:LonelyPages - content that appear here are either purposefully left unlinked to because they are under development, or neglectfully because they have become unattached.
Wiki Unused Files Report: https://www.idigbio.org/wiki/index.php/Special:UnusedFiles - content that appears here is usually mis-formatted in their attachment link but not orphaned. Making sure all of content here is referenced can also reveal redundant or abandoned files. If a Wiki document is referenced in a Drupal document,, it will still show up in this report as 'unused'. And in the same way, the Wiki Tools->What Links Here report will miss the relationship also.
Drupal offers a Link Rot Report, but it often contains a lot of false positives, especially in the domain of 'tiny URLs'.

References to Drupal tags and Wiki categories

Audience definition tags

These were the categories we used to define our web presence audience; they represent distinct groups of web content consumers with their own areas of interest.

Educator
Researcher
Citizen scientist
General public: adult, youth (K-12)
Public media
IT
Student
Museum staff
Policy maker
ADBC partner (TCN / PEN, etc.)
iDigBio staff

Content definition tags

Policy
Digitization
Data ingestion
Database
Workflow
Cyberinfrastructure
Blog = Article, Report, e.g., Trip report, Meeting report
Documentation = White paper
Education
Outreach
Public Participation: Citizen Science
Multimedia: Brochure, Pamphlet, Poster, Video
Working group: aOCR, CYWG (Cyberinfrastructure), Georeferencing, Biodiversity Informatics, Public Participation, DROID, Whole-drawer, etc. (includes Interest group)
Workshop
Information
Research

Content-specific tags

Any other terms that someone might use when conceiving of a category to search for, or a specific definitive detail, e.g., Hirox, Open Refine (note, this is an exception to the capitalization rule for tags, and is valid because this is a title).

Wiki references on categories