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

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: