Sessions at Open Source Bridge 2011 about Documentation

Your current filters are…

Tuesday 21st June 2011

  • "Don't Give that Book Away!": Why Every Project Needs an Open Source Book

    by Tim O'Brien

    Your open source project is "revolutionary", but no one knows how to install your software and new users are complaining about documentation. What you need is a book, and you need it fast! If your project catches their attention, you'll quickly be approached by one or more publishers.

    *What do you do?*

    The first half of this talk delves into this particular decision point. Should you publish with a publisher, or should you just write an open source book? We'll explore the advantages and disadvantages of open source books and provide attendees with one model for making such a decision.

    • What effect does open source documentation have on the adoption curve of a new technology?
    • What is the "lifecycle" of a traditional (published) book?
    • Who owns a published book? and How is it distributed?

    The second half of this talk explores the technical infrastructure, tools, and cultural mechanisms that best support an ongoing documentation effort.

    • Open Source documentation "governance": how it works
    • Who manages the open source documentation project?
    • What is in a sample open source publishing pipeline?
    • How can open source documentation be used to support an open source business model?

    Attendees will explore the infrastructure behind two publishing pipelines and explore the various options that are available to a project that has decided to take responsibility for production.

    At 10:00am to 10:45am, Tuesday 21st June

    Coverage note

  • Read the Docs: A Completely Open Source Django Web Site

    by Eric Holscher

    Hosting open source documentation was a mess. The best-of-class solution for the Python world as uploading a tarball of html to packages.python.org or doing similar to upload to github pages. If you wanted to self-host it, that generally meant having a cron job that ran a shell script to pull your source code nightly. We set out to solve this problem using the current best of class tools that Django has to offer.

    "Read the Docs":http://readthedocs.org/ is the official documentation host for many open source Python projects. It is built around the "Sphinx":http://sphinx.readthedocs.org/en/latest/index.html documentation toolkit. In the simplest form, we are a hosting provider for Sphinx documentation. However, we have added a lot of features to make this useful. These include:

    • Support for svn, hg, git, and bzr.
    • Post-commit hooks to automatically build documentation on commit
    • A custom Read the Docs styled Sphinx theme.
    • Full-text search across all projects.
    • Support for VCS tags and branches. (branches git only for now)
    • PDF generation for all documentation.
    • Editing of documentation that results in a pull request on github. (Bitbucket doesn't have a pull request API)

    Read the Docs has a lot of the standard parts of any website, and also some other intersting parts that are relatively unique. These include:

    • Subdomains
    • CNAME Support
    • Search using Solr and Haystack
    • Delayed task execution with Celery
    • Front end caching with Varnish
    • Deployment with Chef
    • Multi-server architecture
    • Monitoring with Nagios and Munin

    This talk will consist of three parts. The first part is the origin story of the site, how and why it was created over a weekend by 3 people. Then I'll talk about the technology involved as the site has grown. It started out as a very simple site, but as features have been added, it has gotten more complex. Finally I will discus some of the interesting outcomes that come from having a completely open source site, including security and community contributions.

    At 10:00am to 10:45am, Tuesday 21st June

    Coverage note

Wednesday 22nd June 2011

  • Preventing Runtime Errors at Compile Time

    by Michael Ernst, David Lazar and Werner M. Dietl

    Are you tired of null pointer exceptions, unintended side effects, SQL injections, concurrency errors, mistaken equality tests, and other run-time errors that appear during testing or in the field? A pluggable type system can guarantee the absence of these errors, and many more real, important bugs.

    Are you a software architect who wants to be able to quickly and easily implement custom checks that prevent more errors at compile time? You need a framework that supports you in creating a formally correct code checker.

    This presentation is aimed at both audiences. A pluggable type system can give a compile-time guarantee of important properties. We will explain what it is, how to use it, and even how to create your own. You can create a simple pluggable type-checker in 2 minutes, and you can enhance it thereafter.

    The demo uses the Checker Framework, which enables you to create pluggable type systems for Java. It takes advantage of features planned by Oracle for Java 8, but your code remains backward-compatible. The pluggable type-checker can be run as part of javac or via an Eclipse plug-in, and integration with build tools such as Ant and Maven is provided. The tools are "freely available":http://types.cs.washington.edu/checker-framework/.

    The Checker Framework provides 12 pluggable type systems that are ready to use, including nullness, immutability, and locking checkers. The presentation will first develop a simple declarative type checker that checks the consistency of method signature strings. The presentation will then discuss the design and usage of more advanced checkers.

    The Checker Framework has found hundreds of bugs in over 3 million lines of open source code, including from Oracle, Google, Apache, etc. Overall, we found that the type checkers were easy to write, easy for novices to productively use, and effective in finding real bugs and verifying program properties, even for widely tested and used open source projects. It is easy to improve the quality of your Java code, and you can start using the Checker Framework today!

    At 10:00am to 11:45am, Wednesday 22nd June

    Coverage note