• Share
  • Email
  • Embed
  • Like
  • Save
  • Private Content
Jonathan Callahan   Plone For Government Science    How To Get Buy In From Managers, Security Watchdogs And Colleagues

Jonathan Callahan Plone For Government Science How To Get Buy In From Managers, Security Watchdogs And Colleagues



This talk will present my experiences setting up Plone for two software development groups within the US Governement's NOAA and NASA agencies. In the past, each of these groups created documentation ...

This talk will present my experiences setting up Plone for two software development groups within the US Governement's NOAA and NASA agencies. In the past, each of these groups created documentation for internal development and external 'end users' with a combination of static HTML pages and semi-automated tools such as mail archivers and task managers. The adoption of Plone by these groups has greatly increased the quantity, accuracy and usability of their documentation. Content is now easier to create, easier to find and easier to read. Getting these groups to accept Plone as a Content Management System was not always easy and required buy-in from managers, agency computer security types and colleagues. I will discuss my experiences with the following hurdles: 1) selling Plone to your boss; 2) working with the computer security watchdogs; 3) training your colleagues to use Plone consistently; and 4) becoming a plone guru in 4 hours/week. Attendees should be familiar with basic Plone configuration and will learn techniques for making Plone useful within an agency science setting.



Total Views
Views on SlideShare
Embed Views



1 Embed 1

http://www.slideshare.net 1



Upload Details

Uploaded via as Microsoft PowerPoint

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
Post Comment
Edit your comment

    Jonathan Callahan   Plone For Government Science    How To Get Buy In From Managers, Security Watchdogs And Colleagues Jonathan Callahan Plone For Government Science How To Get Buy In From Managers, Security Watchdogs And Colleagues Presentation Transcript

    • Plone for Government Science Getting buy-in from mangers, security watchdogs, and colleagues. Jonathan Callahan Mazama Science
    • Plone for documenting software Experiences from the world of government science.
    • Who am I?
      • Consultant for web based access to scientific data and visualizations
      • PhD in Chemistry
        • magnetic resonance simulation, visualization and UI design
      • 12 years working for NOAA
        • Visualization and UI design for climate data
      • 2 years working for EPA
        • Visualization and UI design for water quality data
      • 1 year working for NASA
        • UI design for a climate metadata catalog
    • My connection to Plone
      • Convinced, coerced & cajoled NOAA group to adopt Plone
      • Attended ‘skinning’ workshop at Seattle Plone conference
      • Am currently the Plone advocate within the NOAA and NASA groups
      • Still only devote < 4hrs/week to plone
    • the Neophyte
    • Scientific software
      • Scientific software is developed by groups within academia or government institutions.
      • Group leaders have a background in science, not business.
      • Feature requests always outstrip available resources.
      • Developers are attracted to the latest challenges.
      • Documentation tends to be poor.
    • Past experience with documentation tools
      • Tools are hard to learn.
      • Tools cost money.
      • Tools are difficult to work with.
      • Tools don’t handle collaborative editing.
      • No obvious choices for documenting software.
      • Writing documentation is not a funded activity.
    • What we need in a CMS
      • Ease of use (WYSIWYG)
      • Structure (outline, chapters, subchapters, etc.)
      • Consistency
      • Searchability
      • We want to create a book, not a blog.
    • Why we need to create good documentation
      • Helps us understand what we’re doing.
      • Lets us answer email questions with a URL.
      • Makes our software accessible to more people.
      • Creates institutional memory
    • Institutional memory
      • Making progress in science involves writing things down.
      • Research done 40 or 100 years ago is still relevant.
      • Code written 30 years ago is still in use.
      • Institutional science needs easy ways to create good book-length documentation.
      • Wikis can be too disorganized.
      • IRC chat is not a good model for science.
    • IRC style communication (good for communicating now )
    • Scientific style communication (good for communicating through time )
    • Institutional memory
      • Journal articles
      • Books
      • Procedures & Protocols
      • Structured, stable, consistent, comprehensive
    • Note to Plonistas
      • Government institutions typically have the IRC port turned off for security reasons.
      • IRC is completely unknown to most folks in the scientific community.
      • If IRC is the best (or only) way to get good information, government institutions will be cut off.
      • IRC doesn’t create institutional memory.
    • NOAA LAS (Live Access Server)
    • Internal documentation needs
      • Developer documentation
      • Code overview
      • How-to’s and code snippets
      • Internal white papers
    • E xternal documentation needs
      • Developer documentation
      • Installer documentation
      • End user documentation
      • Public face
    • Software documentation examples
    • Software documentation examples
    • Common elements of best sites
      • Typographical conventions
      • Hierarchical outline
      • Easy searchability
      • Consistent style
    • Plone is an excellent fit
      • Highly structured
      • Easy to enter content
      • Easy to search
      • Active developer community
      • Based on Python
        • Lots of good scientific code being written in Python.
    • Hurdles to adopting Plone
      • Convincing the boss to commit to Plone
      • Becoming a plone guru in your spare time
      • Training colleagues to use it consistently
      • Working within institutional security restrictions
    • Convincing the boss
      • What the boss wants:
        • Make good documentation happen with as little effort as possible.
      • What the boss worries about:
        • Getting locked into a system that requires a guru.
        • Spending too much time maintaining the system.
        • Picking a system that won’t be around very long.
        • Inability to export to another system.
    • Convincing the boss
      • How to convince the boss:
        • Show them existing sites of similar nature.
        • Set up Plone to demonstrate how easy it is.
        • Cut-and-paste import a few static web pages to demonstrate searchability.
        • Import large amounts of documentation and present them with a fait accompli .
        • Demonstrate export as static web pages.
    • Learning Plone in 4 hrs/week
      • Set up Plone on your home computer.
      • Poke around the Site Admin pages.
      • Read docs on plone.org/documentation/. (They get better every month.)
      • Learn to use IRC for quick answers.
      • Create additional Plone sites on top of the same Zope at your institution for testing. (Use ZMI to copy between sites.)
    • Working with colleagues
    • Working with colleagues
      • Colleagues don’t like writing documentation.
      • Colleagues don’t have time to read Plone documentation.
      • Colleagues can’t read your mind regarding organization and style.
      • Make it as easy as possible!
    • How-to’s for common tasks
    • Typographical conventions
    • Documentation outline
    • Source code docs
    • Source code docs
      • Javadoc and JSDoc create excellent HTML documentation from well documented source code.
      • Use Javadoc/JSDoc flags to strip off headers and footers.
      • Use Plone “Edit without visual editor“ link to paste in raw HTML.
      • Tweak HTML to remove any offending lines.
      • Or, write a script to preprocess Javadoc output.
    • Error messages
    • Multiple plone sites
      • Multiple sites provide
        • Search separation between projects/releases
        • Different users for each project/release
        • Unique URL identity for each project/release
    • Plone for software documentation
      • Plone is well suited to create excellent documentation.
      • If anything it is too feature-rich.
      • Create the outline and style guidelines first.
      • Simplify the UI to ensure consistent documentation.
      • Don’t force contributors to become Plone gurus.
      • Put different projects in different Plone sites.
    • Working with security
    • Security perspective
      • Directives of ‘zero tolerance’ come down from above.
      • The computer security guys catch hell if there is a security breach.
      • They will not allow non-secure logins to a government system.
      • They don’t have time to learn about Plone’s security features.
    • Solution: display only Plone site
      • One version of Plone inside the firewall with contributor users.
      • A second version of Plone outside the firewall with only the ‘admin’ user.
      • ‘ join’ and ‘login’ have been disabled and templates modified on external Plone.
      • All documentation in a single ‘/home’ folder.
      • Use export/import to move updated content outside the firewall.
    • Suggestions for groups new to Plone
      • Create a documentation outline.
      • Create excruciatingly detailed, cookbook instructions on how to do simple tasks.
      • Reorganize contributions back toward the outline.
      • Don’t add any products you don’t need.
      • Keep things as simple as possible!
    • Experience so far
      • Some developers still won’t write documentation.
      • Others love the system and write lots.
      • Someone must be identified to make executive decisions about the structure of documentation.
      • Much internal information has moved from email into Plone because of searchability.
      • External documentation is easier for outsiders to use and for us to maintain.
    • Review of goals
      • Consistency
      • Structure
      • Ease of use
      • Searchability
    • Personal commitment
      • Learn Plone in your spare time.
      • Push to have it adopted.
      • Write documentation on how to use it.
      • Work with colleagues having difficulties.
      • Organize group information if it isn’t already.
    • Personal payoff
      • Satisfaction of a job well done.
      • Fewer answers delivered by IRC/phone/email.
      • You might be invited to speak at a Plone conference. ;-)
    • Government science payoff
      • Better documentation.
      • Easier to find documentation.
      • Easier to guide the creation of documentation from the top down.
      • Established system for creating Institutional Memory
    • Plone payoff
      • Government science desperately needs something like Plone to help create better documentation.
      • Government science has many tech-savvy individuals who can set up Plone.
      • Adoption by Government science provides a long term advocate.