Create Sphinx Page policy

[jburel]

Define the policy for writing a page.

Initial Draft subject to review:

For each page, you need to capture (at a bare minimum) the following information:

• Description: The title of the content item.
• Content Owner: This is generally the department or individual responsible for the content item.
• Format: Formats include hard copy, electronic file (Word/Excel?/PDF, etc.), and links.
• Location: This is the location of the content item. Locations include URLs, the hard drive of an individual, a shared directory, or file drawer in the basement of the building.
• Update Frequency: Include “Frequent”, “Sometimes”, or “Rarely” flags in your inventory. Frequently updated content generally requires a higher profile in the navigation schema.
• Status: The status of content can be current, obsolete (generally content on the current site that will not be migrated), or to be created.
• General Notes: If the content requires special treatment or you have additional information to capture, note it in this section of the content inventory.

Additional heuristics that will need to be considered:

• Collocation
  • Bring together items with similar content or items about the same topic in one area.

• Differentiation
  • Place dissimilar items or items about different subject areas in different content areas. Use navigation labels for different areas that clearly indicate those differences.

• Completeness
  • All content mentioned or linked to should exist.

• Information scent
  • Content labels should be appropriately descriptive of content so that users know they are on the proper path to finding the information they are looking for. Content labels should therefore also reflect information collocation and differentiation.“Don’t use made-up words or your own slogans as navigation options, since they don’t have the scent of the sought-after item.

Plain language also works best for search engine visibility: searching provides a literal match between the words in the user’s mind and the words on your site.”

• Bounded horizons
  • A site’s users should be able to easily understand the breadth of content they are looking at.

• Accessibility
  • Users should be able to access the content they want through the browsing hierarchy or by using search.

• Multiple access paths
  • Because users think about content in different ways, they should be able to take multiple paths to get to specific content.

• Appropriate structure
  • Organization of content should
  • (1) match users’ mental models of the information space and
  • (2) support the differences in users’ information-seeking behaviors: known-item finding; exploratory browsing; unknown information finding; and refinding.

• Consistency
  • Whenever possible, content structures in similar content areas should be consistent. (See above format this will be required to be applied through the entire site with only minor alterations to ensure a consistent level of consistency.)

• Audience-relevance
  • Content organization allows different audience segments to easily find relevant content.

• Currency
  • Content should be kept up to date. We will need to identify the core set of pages that need regular updates and

ensure that the person responsible for the page updates the information at the set intervals.

[jmoore]

Scott, let's make sure this info gets into the unified policy page.

[wmoore]

• "Location", "Accessibility", Collocation" & "Appropriate structure" should be handled by first finding the place in the SiteMap hierarchy that your new page belongs. If there is a page there that has similar content to what you are planning, you should probably update that page, instead of creating another. When you have created your page, you should update the SiteMap and the parent page with links to your new page.
• Page Names MUST comply with WikiPageNames. If appropriate, use a hierarchical name to reflect its position in SiteMap. E.g. OmeroWeb/CreateApp
• "Bounded horizons" & "Description": Need a good introductory sentence / paragraph.
• "Content Owner" and update history is handled by the wiki history.
• "Currency" & "Status": Need to decide which pages to update based on what changed in each release. E.g API changes => update OmeroJava, OmeroPy etc. Model changes => update OmeModel etc. Hopefully with a well organised site, it should be easier to browse and decide what needs updating.
• "Format". Start pages with a

  = Page Title =
  

[jburel]

Moved from sprint 2011-10-27 (1)

[jmoore]

Referencing ticket #7010 has changed sprint.

[jmoore]

Referencing ticket #7010 has changed sprint.

[jmoore]

Moving to a "sphinx" ticket

[jmoore]

Sebastien, do you think this is something we can finalize for 4.4.4? If not, please push to 4.5.0.

[sbesson]

I am not sure I am the right person to address this. Pushing to 4.5.0.

May be a good starting ticket for the future technical writer.

[hflynn]

Does this essentially translate to update the README file for OME-documentation??

[jmoore]

Probably. Or perhaps on ome-internal. The idea being that there is a clear mechanism (or review process) for new pages. This is somewhat historical in that the wiki quickly grew with everyone editing and Will was forced to try to hand create a site-map. Due to the nature of sphinx and the way we use PRs, this might be nearly gone, but it would be nice to keep ourselves in check so that it doesn't happen again. ;)

Another issue which is somewhat related is the "status" or "currency" of the pages, especially things like the FAQ. How frequently do we review all of the content? Etc. Etc.

[sbesson]

Since the migration to Sphinx, many sections have been reviewed and the process for adding new pages/editing existing pages is now part of the culture. Closing this as fixed.