Learning from the Pros(e)

February 26, 2010

When approaching any difficult problem, it is often helpful to examine the solutions to other, similar problems.  Writing documentation is no exception.  So, when presented with the task of documenting a set of application services in a development framework, it would seem reasonable to consult the documentation of similar products.

“Design Patterns”

One piece of documentation which has become a recurring topic of discussion at our team meetings is the much-lauded gang-of-four “Design Patterns” book.  Its value in relation to our task has already been discussed by Brent here.

Microsoft’s .NET

Microsoft’s .NET framework is both mature and corporately-sponsored.  As such, good documentation would be expected.  Of course, documenting the .NET framework in its entirety is a much larger task than documenting application services in e4.  A sub-area of .NET which is at least somewhat analogous, however, is .NET’s Windows Communication Foundation (WCF).

The WFC still contains a lot of documentation, but there are two sub-sections that I find particularly relevant: the Conceptual Overview and the various Feature Details.

The obvious mapping of .NET’s conceptual overview is to an overview of the e4 service model, which is likely something that would not be done by our team.  Given the conceptual approach that we are taking to documenting individual services, though, there are several ideas which could be relevant.

  • The document What is the Windows Communication Foundation contains 3 essential sub-sections:
    • An high-level description of what WCF is/why it exists
    • A concrete problem (car reservation app) that the WCF can be used to solve
    • A summary and subsequent breakdown of how WCF features/principals solve the example problem

    All of this is done in a code-agnostic way. I think the idea of presenting a concrete
    problem and demonstrating how it is solved by the tool (service) at hand would work well in the context of e4 application services.

  • In Fundamental Windows Communication Foundation Concepts, a list of relevant terms and their definitions is provided.  Again, their is no code, save a few references to the names of Classes which define the terms.  I think this would be useful to our service descriptions.  (E.g. If I am describing the Saveable Life Cycle, the reader needs to know something about SaveableParts and a Viewparts).

The documentation of WCF’s features seems like it should be relevant to our project because it describes a set of closely related framework provisions.  After taking a closer look at the documentation for several of these features, there are two things that are worth noting:

  • There isn’t a generalized format for documenting each feature.  In fact, while some features are only allotted a single page, others span many pages and sub-sections.  Even between sections that one would expect to be congruent, such as the “Overview” sections of two features, there is significant variation.  I haven’t formed an opinion on whether this is a good approach, but perhaps an imposed structure is too restrictive.
  • In spite of its lack of a consistent structure, the documentation of WCF’s contains very little code.  If we find that writing code-agnostic documentation is challenging, this documentation could be consulted for further insight.  It is important to note, however, that code is not completely absent.  This description of WCF’s data transfer architecture, for example, still includes non-negligible amounts of code.

Finally, I stumbled upon a pretty cool diagram while surfing the .NET:

.NET Framework Diagram - source

I thought that this type of diagram could be a great way to visually represent the relationship of services to one another, and to Eclipse’s underlying framework.  The core of the circle could represent the framework’s inner workings, with services closer to the outside.  Radial proximity could be used to represent group similar services, and layering of various services could show the dependence of services upon other services.

With my limited knowledge of the e4 service model and how services are related, I’m not sure how well this would work, but it seems like something that is worth mentioning.

“Eclipse Rich Client Platform: Designing, Coding, and Packaging Java Applications”

This book is the definitive guide to Eclipse RCP, and so I thought there was a good chance it would have something to teach us.  Although my examination of its documentation practices was brief, I found its use of an ongoing example to be interesting.

I have already noted the use of example problems in documentation, as is done in .NET’s conceptual overview. The Eclipse RCP book’s use of a single problem to highlight the usefulness of multiple concepts builds upon this idea.  Throughout the book, an instant messaging application is built using the recently discussed tools.  Code snippets are given inline, and the complete source code is provided electronically so that the reader can install and run various iterations of the program as its development progresses.

Certainly, our project doesn’t warrant a coded example.  I do, however, think that the periodic mention of a hypothetical application that incorporates many/all services could be useful.  In addition to demonstrating how each service is useful, it would provide cohesion among our descriptions and potential provide insight into how services are related.


So, to recap the relevant documentation techniques that I have observed:

  • From Microsoft’s .NET (esp WCF)
    • Providing a relevant problem and describing how the topic at hand is a solution
    • Providing a list of relevant terms and definitions (essentially an in-page glossary)
    • Avoiding a concrete template so that the content can dictate the format (form fits function?)
    • Using code snippets sparingly, but not abolishing them altogether
    • Using a cool circular diagram to depict layered services in a framework
  • From the Eclipse RCP book
    • Using a single concrete example across all services

After our Feb 12th meeting with the Boris an McQ, there was unanimous agreement among our team members that we had finally reached a suitable project plan.  The scope of our project had been narrowed from a daunting 20+ services to a much more manageable “several”.  Our primary source of optimism was not the promise of less work, though.  Instead, our optimism resulted from a shift in the type of work we would now endeavour to complete.

Our initial plan of documenting twenty-odd services was quick to demonstrate the deficiency of our Eclipse knowledge.  After creating a basic service template and using it to create initial documentation for a handful of services, Stefan and I reluctantly asked a painful question:  “How is our work different from the (pretty mediocre) documentation which already exists on the e4 wiki?”

Of course, the answer to this question is that it’s not…yet.  Until our last meeting, we had expected to solicit widespread community contributions to fill out our documentation and compensate for our lack of e4 expertise.  In this way, we were to produce in-depth documentation without ever needing in-depth knowledge of what we were documenting.  But our meeting forced us to confront a problem with this plan:  In spite of being engaged and knowledgeable, the Eclipse community would need more than our passive requests to involve itself with our project.

With neither adequate knowledge nor a method to easily obtain it, it was clear that we needed a new game plan.  During our Feb 12 meeting, it quickly became clear that this plan would include a narrowed scope and greater focus on documentation design.  That is, from the diametrically opposed properties of quantity and quality, we had chosen the latter.

Producing high quality documentation for a small number of services solves our knowledge problems on two counts.  First, the narrowed scope allows us to devote more of our limited time to learning about each service.  Instead of shotgun approach to information collection, we can actively (aggressively?) solicit one-on-one communication with developers who know about the services we are interested in.  Second, an increased focus on format allows as to divert some of our efforts from information collection to knowledge creation.  In this way, our final deliverable will not be evaluated solely on the completeness of its information.  Instead, the quality of the method by which  we convey information will equally represent value to the Eclipse team.