OpenOffice.org Lessons Learned

Link to OSCON page.

openoffice.org

• at first most considered openoffice.org a minor annoyance

  • wasn't popular at Sun as it undercut StarOffice

• an alternative to a life of licensed software

• focus on end-users

• changing legacy software mindset

  • move away from monolithic structure

    • “let's cram as much crap into our software as possible”

    • difficult to refactor

  • focus on open data formats

  • ODF standard

    • make open source/standards/formats more palatable to governments and corporations

• focus on extensions

  • allow non-core development

creating a community

• requires a central focus

  • the easiest way is to have a common enememphasize the virtues of what you're doing

• develop a product strategy

  • how do we encourage adoption

• lower the bar of entry for contributing

  • don't just focus on developers

• face-to-face meetings

• architecture shapes community participation

  • monolithic structure limits participation

    • getting new developers is difficult

  • modular structure encourages participation

• ecosystems

  • created around extensions, services, and support

• education

  • need new developers

  • new developers need to be taught how to code and how to contribute

    • not a bunch of untrained developers slowing the process

    • the mythical man-month (throwing more developers at a project does not decrease development time)

Project Documentation

Link to OSCON page.

What is documentation

• first contact with a user

• source of education

• front line of suppport

• consists of

  • conceptual material

  • “how-to”

  • reference material

  • troubleshooting

• communication with people who care about your project

Things to avoid

• Perfection

  • release early and often

• forgetting that your audience is people

qualities of solid documentation

• complete

  • covers all features, usage modes, and interfaces

  • answers essential questions

    • who what where

• correct

  • should match the software, hardware, or device

  • logically organized

  • consistent and professional

• appropriate

  • know who your audience is

    • know what they need to know

    • answers their questions

  • accessible

  • consistent and professional

• what is less important

  • text formats

  • tools

  • delivery format

    • consider mobile devices

  • perfection

• what is not solid

  • missing unmentioned features

  • inconsistent

  • unprofessional

    • grammar, spelling, etc

classical elements of technical documentation

• concepts – what?

  • The 10,000ft overhead view

  • overview

  • brochures, white papers

  • architecture guides

  • focus on education

• Tasks and examples – how?

  • The 10ft overhead view

  • step-by-step guides

  • quickstart guides

  • tutorials

  • training materials

  • focus on usability and consistency

• Reference

  • the 0ft view

  • system reference manuals

  • API guides

  • layout and manufacturing guides

  • maximal cross-references

  • focus on completeness

• troubleshooting

  • the -6ft view, looking up
    

    • when you get here, you've dug yourself in a hole

  • step-by-step diagnostics

  • flowcharts

  • FAQs

  • from the reader's perspective

  • focus on answering questions

readers you must satisfy

• partners

  • sell, extend, promote, or add value to your project

• developers

  • use your project as a basis to start they're own project

• internal

  • inside our organization

• end-users

  • use the end result (and sometimes pay for the privilege)

• community

  • care about your product by choice

critical questions about documentation

• what is it

• why do I need it

• what does it look like

• who's going to make it

• where do I put it

• when do I schedule it

good documentation habits

• be proactive

• begin with the end in mind

• put first things first

• think win/win

• seek first to understand, then be understood

• synergize (buzzword alert)

• sharpen the saw (practice)

Veracity

Link to OSCON page.

sourcegear.com/veracity

ericsink.com

Opensource (Apache v2), current version is v0.3

DVCS advantages

• fast

  • everything is local

• cruise ship

  • disconnected operation

• moscow

  • distributed teams

  • offshoring

• dell

  • scale out instead of up

  • no need for $$$ servers

  • add another dell

• lego

  • complex processes

Trend is toward integration; this doesn't work well with dvcs

• bug tracking

• wiki

• etc

Other solutions

• ditz

• tcgit

• git-issues

• Bugs Everywhere

Veracity

• decentralized database

• template driven merge

  • automerge based on rules in the template

    • Json (json.org)

    • automerge is correct if the template defines it to be correct

    • possible to define a template such that automerge never fails

    • log of automerge changes

    • conflicting changes

      • two people modify the same record and field

        • most recent

        • highest value

        • resolve by group (dev vs qa)

    • unique constrains

      • GUIDs

        • concatenate a level 1 UUID and level 4 UUID

        • not a friendly id

      • uniqify

        • on merge, if a merge result violates unique constraint, the template defines the resolution

      • create friendly ids, then uniqify if necessary

        • userid + incrementing integer

        • if conflict, increment integer again