Content Style Guide and Workflow

Audience: iDigBio Drupal content creators, iDigBio Wiki content creators

The following are some guidelines to help content creators make consistent documents.

Suggested style elements

Where possible or applicable, every document should have these elements below for ease of contextual placement

1. date
2. version
3. audience
4. tags

Content tagging

Our document 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, but there is no need to re-iterate terms that are in the title.

Effort should be made to use the same universe of tags in both content systems.

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

• Blog is a special Drupal tag that makes sure the content shows up on this page https://www.idigbio.org/news, under 'News Articles'

Put the tag(s) you choose into the 'Tags' field when you 'Add Content'.

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.

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 are restricted to MIME types that do not pose any potential threat to the security of the repository.

When to use Forums

Forums are a place for the community to discuss issues related to biodiversity-related software, workflows, technology, standards, etc. Their activity ebbs and flows depending on the subject.

When to use Drupal

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

For iDigBio staff and named working groups or participants, there is a feature to upload files via our content management system. The only restrictions on this space are the physical limitations of our servers and file system. The easiest way to use this service is to log into iDigBio and visit:

https://www.idigbio.org/imce

Authorized users see a file browser. You can see that 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 this content 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. Once you have filled in the link to the document, given it the appropriate tags (see above), make it published. Note: the state of being 'Unpublished' does not prevent a document from being found via the iDigBio Google search box. If you want it to be in the homepage carousel, be sure to give it the 'Featured' tag.

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

Every individual workshop presentation should be uploaded as a PDF, and a biblio record created for it.

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

Linking to content - Wiki

Attention needs to be paid to representing that link to the 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 sometime 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 '|'.

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

Editing Content

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

Editing Content - Drupal

It is not advisable to include more than paragraph

, line breaks
in text, and to avoid blanket copy/pasting from Word documents. The pasted text from Word includes a lot of unnecessary font treatment markup. Let the text you want to insert follow the native Drupal style embedded in the website. Help in special formatting features like lists is possible via the 'Source' button in the content editor

Editing Content - Wiki

The first place to look at the markup is in the Media Wiki intro to formatting and a larger trove of help MediaWiki Help. It is advisable in the long run to use the native markup. There is a Sandbox feature to help you get started with Wiki syntax. One efficient strategy is to find a page example you like in an existing page and copy it into your own document.

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:

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

the right parameter indicates placement in the text block and the 400px parameter scales it to fit.

Searching

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

1. a plain Google search
2. a site specific Google search
3. a site specific Wiki search - returns only Wiki pages
4. using the browser find command (^f) - 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.

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