Plone for Government Science Getting buy-in from mangers, security watchdogs, and colleagues. Jonathan Callahan Mazama Sci...
Plone for documenting software Experiences from the world of government science.
Who am I? <ul><li>Consultant for web based access to scientific data and visualizations </li></ul><ul><li>PhD in Chemistry...
My connection to Plone <ul><li>Convinced, coerced & cajoled NOAA group to adopt Plone </li></ul><ul><li>Attended ‘skinning...
the Neophyte
Scientific software <ul><li>Scientific software is developed by groups within academia or government institutions. </li></...
Past experience with documentation tools <ul><li>Tools are hard to learn. </li></ul><ul><li>Tools cost money. </li></ul><u...
What we need in a CMS <ul><li>Ease of use (WYSIWYG) </li></ul><ul><li>Structure (outline, chapters, subchapters, etc.) </l...
Why we need to create good documentation <ul><li>Helps us understand what we’re doing. </li></ul><ul><li>Lets us answer em...
Institutional memory <ul><li>Making progress in science involves writing things down. </li></ul><ul><li>Research done 40 o...
IRC style communication (good for communicating  now )
Scientific style communication (good for communicating  through time )
Institutional memory <ul><li>Journal articles </li></ul><ul><li>Books </li></ul><ul><li>Procedures & Protocols </li></ul><...
Note to Plonistas <ul><li>Government institutions typically have the IRC port turned off for security reasons. </li></ul><...
NOAA LAS (Live Access Server)
Internal documentation needs <ul><li>Developer documentation </li></ul><ul><li>Code overview </li></ul><ul><li>How-to’s an...
E xternal   documentation needs <ul><li>Developer documentation </li></ul><ul><li>Installer documentation </li></ul><ul><l...
Software documentation examples
Software documentation examples
Common elements of best sites <ul><li>Typographical conventions </li></ul><ul><li>Hierarchical outline </li></ul><ul><li>E...
Plone is an excellent fit <ul><li>Highly structured </li></ul><ul><li>Easy to enter content </li></ul><ul><li>Easy to sear...
Hurdles to adopting Plone <ul><li>Convincing the boss to commit to Plone </li></ul><ul><li>Becoming a plone guru in your s...
Convincing the boss <ul><li>What the boss wants: </li></ul><ul><ul><li>Make good documentation happen with as little effor...
Convincing the boss <ul><li>How to convince the boss: </li></ul><ul><ul><li>Show them existing sites of similar nature. </...
Learning Plone in 4 hrs/week <ul><li>Set up Plone on your home computer. </li></ul><ul><li>Poke around the Site Admin page...
Working with colleagues
Working with colleagues <ul><li>Colleagues don’t like writing documentation. </li></ul><ul><li>Colleagues don’t have time ...
How-to’s for common tasks
Typographical conventions
Documentation outline
Source code docs
Source code docs <ul><li>Javadoc and JSDoc create excellent HTML documentation from well documented source code. </li></ul...
Error messages
Multiple plone sites <ul><li>Multiple sites provide </li></ul><ul><ul><li>Search separation between projects/releases </li...
Plone for software documentation <ul><li>Plone is well suited to create excellent documentation. </li></ul><ul><li>If anyt...
Working with security
Security perspective <ul><li>Directives of ‘zero tolerance’ come down from above. </li></ul><ul><li>The computer security ...
Solution: display only Plone site <ul><li>One version of Plone inside the firewall with contributor users. </li></ul><ul><...
Suggestions for groups new to Plone <ul><li>Create a documentation outline. </li></ul><ul><li>Create excruciatingly detail...
Experience so far <ul><li>Some developers still won’t write documentation. </li></ul><ul><li>Others love the system and wr...
Review of goals <ul><li>Consistency </li></ul><ul><li>Structure </li></ul><ul><li>Ease of use </li></ul><ul><li>Searchabil...
Personal commitment <ul><li>Learn Plone in your spare time. </li></ul><ul><li>Push to have it adopted. </li></ul><ul><li>W...
Personal payoff <ul><li>Satisfaction of a job well done. </li></ul><ul><li>Fewer answers delivered by IRC/phone/email. </l...
Government science payoff <ul><li>Better documentation. </li></ul><ul><li>Easier to find documentation. </li></ul><ul><li>...
Plone payoff <ul><li>Government science desperately needs something like Plone to help create better documentation. </li><...
Upcoming SlideShare
Loading in...5
×

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

2,290

Published on

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.

Published in: Technology
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
2,290
On Slideshare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
54
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide

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

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

    Clipping is a handy way to collect important slides you want to go back to later.

×