Content Style Guide and Workflow

Audience: iDigBio content creators (Wiki, Drupal, and Redmine)
Version: DRAFT 4 Feb 2014

Purpose

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.

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" though.

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.

1. tags (called 'categories' in Wiki terminology)
2. audience
3. version
4. date

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 file 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.

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

Workshop content includes the Powerpoint presentations and the 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.

• https://www.idigbio.org/#overlay=node/add/biblio

When to use Forums

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:

• Wiki Formatting
• Redmine Formatting

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:

1. mark it Published if you are ready,
2. put the tag Featured into the tags field if you want it to appear in the carousel on the home page,
3. 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

• Active voice
• more.....

Content tagging

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 which are normally used in the plural 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’

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
• 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.

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

Reviewing

needs content - every Drupal doc needs a review? Suzette?

Searching

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

1. a plain Google search
2. a site specific Google search - returns content where the title or tags satisfy the search terms, but does not search PDFs
3. a site specific Wiki search - returns only Wiki pages whose content contains those words
4. using the Wiki Content by category search - returns documents strictly by the explicit category tags in the content.
5. 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.

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:

1. 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.
2. 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.
3. 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.

1. Educator
2. Researcher
3. Citizen scientist
4. General public: adult, youth (K-12)
5. Public media
6. IT
7. Student
8. Museum staff
9. Policy maker
10. ADBC partner (TCN / PEN, etc.)
11. iDigBio staff

Content definition tags

1. Policy
2. Digitization
3. Data ingestion
4. Database
5. Workflow
6. Cyberinfrastructure
7. Blog = Article, Report, e.g., Trip report, Meeting report
8. Documentation = White paper
9. Education
10. Outreach
11. Public Participation: Citizen Science
12. Multimedia: Brochure, Pamphlet, Poster, Video
13. Working group: aOCR, CYWG (Cyberinfrastructure), Georeferencing, Biodiversity Informatics, Public Participation, DROID, Whole-drawer, etc. (includes Interest group)
14. Workshop
15. Information

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 proper noun).

Wiki references on categories

• Wiki category lists and navigation templates
• Wikipedia Catagorization
• iDigBio Wiki categories