Plone forPlone forGovernment ScienceGovernment Science

Getting buy-in from mangers,Getting buy-in from mangers,

security watchdogs,security watchdogs,

and colleagues.and colleagues.

Jonathan CallahanJonathan CallahanMazama ScienceMazama Science

Plone for documenting Plone for documenting softwaresoftware

Experiences from the world of Experiences from the world of government science.government science.

Who am I?Who am I?

► Consultant for web based access to scientific Consultant for web based access to scientific data and visualizationsdata and visualizations

► PhD in ChemistryPhD in Chemistry magnetic resonance simulation, visualization and magnetic resonance simulation, visualization and

UI designUI design► 12 years working for NOAA12 years working for NOAA

Visualization and UI design for climate dataVisualization and UI design for climate data► 2 years working for EPA2 years working for EPA

Visualization and UI design for water quality dataVisualization and UI design for water quality data► 1 year working for NASA1 year working for NASA

UI design for a climate metadata catalogUI design for a climate metadata catalog

My connection to PloneMy connection to Plone

►Convinced, coerced & cajoled NOAA Convinced, coerced & cajoled NOAA group to adopt Plonegroup to adopt Plone

►Attended ‘skinning’ workshop at Attended ‘skinning’ workshop at Seattle Plone conferenceSeattle Plone conference

►Am currently the Plone advocate within Am currently the Plone advocate within the NOAA and NASA groupsthe NOAA and NASA groups

►Still only devote < 4hrs/week to ploneStill only devote < 4hrs/week to plone

the Neophytethe Neophyte

Scientific softwareScientific software

► Scientific software is developed by groups Scientific software is developed by groups within academia or government institutions.within academia or government institutions.

► Group leaders have a background in science, Group leaders have a background in science, not business.not business.

► Feature requests always outstrip available Feature requests always outstrip available resources.resources.

► Developers are attracted to the latest Developers are attracted to the latest challenges.challenges.

► Documentation tends to be poor.Documentation tends to be poor.

Past experience with Past experience with documentation toolsdocumentation tools

► Tools are hard to learn.Tools are hard to learn.► Tools cost money.Tools cost money.► Tools are difficult to work with.Tools are difficult to work with.► Tools don’t handle collaborative editing.Tools don’t handle collaborative editing.► No obvious choices for documenting software.No obvious choices for documenting software.

► Writing documentation is not a funded activity.Writing documentation is not a funded activity.

What we need in a CMSWhat we need in a CMS

►Ease of use (WYSIWYG)Ease of use (WYSIWYG)►Structure (outline, chapters, Structure (outline, chapters,

subchapters, etc.)subchapters, etc.)►ConsistencyConsistency►SearchabilitySearchability

► We want to create a book, not a blog.We want to create a book, not a blog.

Why we need to create good Why we need to create good documentationdocumentation

► Helps us understand what we’re doing.Helps us understand what we’re doing.► Lets us answer email questions with a URL.Lets us answer email questions with a URL.► Makes our software accessible to more Makes our software accessible to more

people.people.

► Creates Creates institutional memoryinstitutional memory

Institutional memoryInstitutional memory

► Making progress in science involves writing Making progress in science involves writing things down.things down.

► Research done 40 or 100 years ago is still Research done 40 or 100 years ago is still relevant.relevant.

► Code written 30 years ago is still in use.Code written 30 years ago is still in use.► Institutional science needs easy ways to Institutional science needs easy ways to

create good book-length documentation.create good book-length documentation.► Wikis can be too disorganized.Wikis can be too disorganized.► IRC chat is IRC chat is notnot a good model for science. a good model for science.

IRC style communicationIRC style communication(good for communicating (good for communicating nownow))

Scientific style communicationScientific style communication(good for communicating (good for communicating through through

timetime))

Institutional memoryInstitutional memory

► Journal articlesJournal articles►BooksBooks►Procedures & ProtocolsProcedures & Protocols

►Structured, stable, consistent, Structured, stable, consistent, comprehensivecomprehensive

Note to PlonistasNote to Plonistas

►Government institutions typically have Government institutions typically have the IRC port turned off for security the IRC port turned off for security reasons.reasons.

► IRC is completely unknown to most folks IRC is completely unknown to most folks in the scientific community.in the scientific community.

► If IRC is the best (or only) way to get If IRC is the best (or only) way to get good information, government good information, government institutions will be cut off.institutions will be cut off.

► IRC doesn’t create institutional memory.IRC doesn’t create institutional memory.

NOAA LASNOAA LAS(Live Access Server)(Live Access Server)

Internal documentation Internal documentation needsneeds

►Developer documentationDeveloper documentation►Code overviewCode overview►How-to’s and code snippetsHow-to’s and code snippets► Internal white papersInternal white papers

EExternalxternal documentation documentation needsneeds

►Developer documentationDeveloper documentation► Installer documentationInstaller documentation►End user documentationEnd user documentation►Public facePublic face

Software documentation Software documentation examplesexamples

Software documentation Software documentation examplesexamples

Common elements of best Common elements of best sitessites

►Typographical conventionsTypographical conventions►Hierarchical outlineHierarchical outline►Easy searchabilityEasy searchability►Consistent styleConsistent style

Plone is an excellent fitPlone is an excellent fit

►Highly structuredHighly structured►Easy to enter contentEasy to enter content►Easy to searchEasy to search►Active developer communityActive developer community►Based on PythonBased on Python

Lots of good scientific code being written Lots of good scientific code being written in Python.in Python.

Hurdles to adopting PloneHurdles to adopting Plone

►Convincing the boss to commit to Convincing the boss to commit to PlonePlone

►Becoming a plone guru in your spare Becoming a plone guru in your spare timetime

►Training colleagues to use it Training colleagues to use it consistentlyconsistently

►Working within institutional security Working within institutional security restrictionsrestrictions

Convincing the bossConvincing the boss

►What the boss wants:What the boss wants: Make good documentation happen with as little Make good documentation happen with as little

effort as possible.effort as possible.

►What the boss worries about:What the boss worries about: Getting locked into a system that requires a Getting locked into a system that requires a

guru.guru. Spending too much time maintaining the Spending too much time maintaining the

system.system. Picking a system that won’t be around very long.Picking a system that won’t be around very long. Inability to export to another system.Inability to export to another system.

Convincing the bossConvincing the boss

►How to convince the boss:How to convince the boss: Show them existing sites of similar nature.Show them existing sites of similar nature. Set up Plone to demonstrate how easy it is.Set up Plone to demonstrate how easy it is. Cut-and-paste import a few static web Cut-and-paste import a few static web

pages to demonstrate searchability.pages to demonstrate searchability. Import large amounts of documentation and Import large amounts of documentation and

present them with a present them with a fait accomplifait accompli.. Demonstrate export as static web pages.Demonstrate export as static web pages.

Learning Plone in 4 hrs/weekLearning Plone in 4 hrs/week

►Set up Plone on your home computer.Set up Plone on your home computer.►Poke around the Site Admin pages.Poke around the Site Admin pages.►Read docs on plone.org/documentation/.Read docs on plone.org/documentation/.

(They get better every month.)(They get better every month.)►Learn to use IRC for quick answers.Learn to use IRC for quick answers.►Create additional Plone sites on top of Create additional Plone sites on top of

the same Zope at your institution for the same Zope at your institution for testing. (Use ZMI to copy between sites.)testing. (Use ZMI to copy between sites.)

Working with colleaguesWorking with colleagues

Working with colleaguesWorking with colleagues

►Colleagues don’t like writing Colleagues don’t like writing documentation.documentation.

►Colleagues don’t have time to read Plone Colleagues don’t have time to read Plone documentation.documentation.

►Colleagues can’t read your mind Colleagues can’t read your mind regarding organization and style.regarding organization and style.

►Make it as easy as possible!Make it as easy as possible!

How-to’s for common tasksHow-to’s for common tasks

Typographical conventionsTypographical conventions

Documentation outlineDocumentation outline

Source code docsSource code docs

Source code docsSource code docs

► Javadoc and JSDoc create excellent HTML Javadoc and JSDoc create excellent HTML documentation from well documented source documentation from well documented source code.code.

► Use Javadoc/JSDoc flags to strip off headers Use Javadoc/JSDoc flags to strip off headers and footers.and footers.

► Use Plone “Edit without visual editor“ link to Use Plone “Edit without visual editor“ link to paste in raw HTML.paste in raw HTML.

► Tweak HTML to remove any offending lines.Tweak HTML to remove any offending lines.► Or, write a script to preprocess Javadoc Or, write a script to preprocess Javadoc

output.output.

Error messagesError messages

Multiple plone sitesMultiple plone sites

►Multiple sites provideMultiple sites provide Search separation between Search separation between

projects/releasesprojects/releases Different users for each project/releaseDifferent users for each project/release Unique URL identity for each Unique URL identity for each

project/releaseproject/release

Plone for software Plone for software documentationdocumentation

►Plone is well suited to create excellent Plone is well suited to create excellent documentation.documentation.

► If anything it is too feature-rich.If anything it is too feature-rich.►Create the outline and style guidelines first.Create the outline and style guidelines first.►Simplify the UI to ensure consistent Simplify the UI to ensure consistent

documentation.documentation.►Don’t force contributors to become Plone Don’t force contributors to become Plone

gurus.gurus.►Put different projects in different Plone sites.Put different projects in different Plone sites.

Working with security

Security perspectiveSecurity perspective

►Directives of ‘zero tolerance’ come Directives of ‘zero tolerance’ come down from above.down from above.

►The computer security guys catch hell The computer security guys catch hell if there is a security breach.if there is a security breach.

►They will not allow non-secure logins to They will not allow non-secure logins to a government system.a government system.

►They don’t have time to learn about They don’t have time to learn about Plone’s security features.Plone’s security features.

Solution: display only Plone Solution: display only Plone sitesite

►One version of Plone inside the firewall One version of Plone inside the firewall with contributor users.with contributor users.

►A second version of Plone outside the A second version of Plone outside the firewall with only the ‘admin’ user.firewall with only the ‘admin’ user.

► ‘‘join’ and ‘login’ have been disabled and join’ and ‘login’ have been disabled and templates modified on external Plone.templates modified on external Plone.

►All documentation in a single ‘/home’ All documentation in a single ‘/home’ folder.folder.

►Use export/import to move updated Use export/import to move updated content outside the firewall.content outside the firewall.

Suggestions for groups new Suggestions for groups new to Ploneto Plone

►Create a documentation outline.Create a documentation outline.►Create excruciatingly detailed, cookbook Create excruciatingly detailed, cookbook

instructions on how to do simple tasks.instructions on how to do simple tasks.►Reorganize contributions back toward Reorganize contributions back toward

the outline.the outline.►Don’t add any products you don’t need.Don’t add any products you don’t need.

►Keep things as simple as possible!Keep things as simple as possible!

Experience so farExperience so far

► Some developers still won’t write Some developers still won’t write documentation.documentation.

► Others love the system and write lots.Others love the system and write lots.► Someone must be identified to make Someone must be identified to make

executive decisions about the structure of executive decisions about the structure of documentation.documentation.

► Much internal information has moved from Much internal information has moved from email into Plone because of searchability.email into Plone because of searchability.

► External documentation is easier for External documentation is easier for outsiders to use and for us to maintain.outsiders to use and for us to maintain.

Review of goalsReview of goals

►ConsistencyConsistency►StructureStructure►Ease of useEase of use►SearchabilitySearchability

Personal commitmentPersonal commitment

►Learn Plone in your spare time.Learn Plone in your spare time.►Push to have it adopted.Push to have it adopted.►Write documentation on how to use it.Write documentation on how to use it.►Work with colleagues having Work with colleagues having

difficulties.difficulties.►Organize group information if it isn’t Organize group information if it isn’t

already.already.

Personal payoffPersonal payoff

►Satisfaction of a job well done.Satisfaction of a job well done.►Fewer answers delivered by Fewer answers delivered by

IRC/phone/email.IRC/phone/email.►You might be invited to speak at a You might be invited to speak at a

Plone conference. ;-)Plone conference. ;-)

Government science payoffGovernment science payoff

►Better documentation.Better documentation.►Easier to find documentation.Easier to find documentation.►Easier to guide the creation of Easier to guide the creation of

documentation from the top down.documentation from the top down.

►Established system for creating Established system for creating Institutional MemoryInstitutional Memory

Plone payoffPlone payoff

►Government science desperately Government science desperately needs something like Plone to help needs something like Plone to help create better documentation.create better documentation.

►Government science has many tech-Government science has many tech-savvy individuals who can set up savvy individuals who can set up Plone.Plone.

►Adoption by Government science Adoption by Government science provides a long term advocate.provides a long term advocate.