Content Style Guide and Workflow: Difference between revisions
No edit summary |
|||
| Line 2: | Line 2: | ||
Audience: iDigBio content creators (Wiki and Drupal)<br> | Audience: iDigBio content creators (Wiki and Drupal)<br> | ||
Version: DRAFT 29 Jan 2014<br> | Version: DRAFT 29 Jan 2014<br> | ||
==Purpose== | |||
The following are guidelines to help content creators make consistent, findable documents. It does not constitute a full and inclusive style guide per se, but seeks to document hidden, little-known features and parameters of our system, and it supports 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 (Jan 2014) and will be provided later. | The following are guidelines to help content creators make consistent, findable documents. It does not constitute a full and inclusive style guide per se, but seeks to document hidden, little-known features and parameters of our system, and it supports 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 (Jan 2014) and will be provided later. | ||
==Suggested style elements== | ==Suggested style elements== | ||
Where possible or applicable, | 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 (categories in Wiki terminology) | #tags (categories in Wiki terminology) | ||
#audience | #audience | ||
Revision as of 15:21, 4 February 2014
Audience: iDigBio content creators (Wiki and Drupal)
Version: DRAFT 29 Jan 2014
Purpose
The following are guidelines to help content creators make consistent, findable documents. It does not constitute a full and inclusive style guide per se, but seeks to document hidden, little-known features and parameters of our system, and it supports 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 (Jan 2014) and will be provided later.
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 (categories in Wiki terminology)
- audience
- version
- date
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.
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. Refer to a list of supported upload file types
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:
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 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.
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 needs to be created for each piece of content.
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 link to content that is in the Drupal 'File browser', see how 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.
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.
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 being aligned (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.
- Be sure 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.....
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:
- 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.
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 on Drupal tags and Wiki categories
Audience definition tags
These were the categories we used to define our web presence audience:
- 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
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 it valid because this is a proper noun).