Exemplar Specifications

[ljnelson]

I've been asked on last week's call to find other (mostly Jakarta) specifications that have good structural parts in them we could emulate as we start to outline our document. Here are some of them, what their good parts are, and why I think we should incorporate their good parts into ours.

I'm putting this in a Github Discussion because the group's consensus is to not use the mailing list.

Servlet

The Servlet specification is well-written. In the Overview section, one of the sub-headings is, simply, "What is a Servlet?" We must do the same sort of thing. (Notably, perhaps alarmingly, we don't yet have a working definition about what configuration is. We need one immediately.)

Next, Servlet offers "An Example" that thankfully is not code. It is an example of the sort of problem and solution that the rest of the specification goes on to specify.

The specification proceeds from the highest levels to the lowest levels, never losing track of the "flow" (the request comes in, is handled, and the response goes out; the document is structured the same way).

Overall I think we should look to the shape and flow of this specification more than any other as we model ours. It is rigorous without being impenetrable and understands what the role of a specification is, which includes not just prescriptive statements but a walkthrough of the general problem area so that the specification comes out looking like a perfectly rational solution to the problem.

RESTful Web Services

I will start with things I don't like and that we should avoid doing.

The first is how the "Goals" section is put together. The very first definition without any preface or lead-in is "POJO-based". This is too dense and jargony to be of any real use to a reader just starting to try to understand what the document is about. We need a Goals section, to be sure, but it needs to help answer the question, "what is this specification trying to do?" Stating, "POJO-based" is not an answer to that question.

I like the idea of the "Terminology" section, but placed up front like it is, the reader has no context to work with. There is a reason that glossaries are usually in the back of a document. Bean Validation (see below) does a better job with this. And contrast this, again, with how the Servlet specification gradually introduces you to concepts you need to know in order to read the document.

I like how the specification makes a deliberate separation between application concerns (concerns related to a group of components), and component concerns (concerns related to a reusable component like a resource class). We will need to do the same.

Faces

Jakarta Faces has a section called "Solving Practical Problems of the Web". Because Jakarta Faces is essentially just a useful library (unlike some other more standards-leaning specifications, like JTA), it has to say not only what problem it is solving, and why, but why it is particularly suited to solving the problem versus some other product. Since Config is targeting, apparently? maybe? both end users (component developers) and vendors (people writing parts of application servers etc.), we should have a similar section.

Faces also explicitly identifies its audiences using Jakarta EE role-based terminology. We must do the same.

Platform

The Jakarta Platform specification has useful structural parts in it.

The most useful part is its definition of roles, which every sub-specification implicitly refers to. We must take care not to redefine these roles and we must be extremely specific about which roles we refer to, given our staggeringly enormous target audiences.

We must also pay attention to the section on namespaces. JNDI exists for a reason quite apart from its underlying technology and that reason is to bridge namespaces baked in to reusable components. Configuration, whatever it is, is all about naming things and names clash.

CDI

The CDI specification in version 4.0 split confusingly and somewhat inconsistently into two sub-specifications combined in one document and did not entirely adjust the document structure to fully match the split. I will therefore look at the 3.0 specification for structural pieces to emulate or incorporate.

The CDI specification puts a "Concepts" section right up front, which I think is the right thing to do. We could look at this approach and blend it with Servlet's "What is a Servlet?" approach. The very first entry we need to come up with, and it will be quite hard, is "What is Configuration?" Answering that question as briefly as possible will nonetheless introduce a few concepts, and then they can be laid out in slightly more detail afterwards, with a glossary/terminology section at the back of the document that goes into great detail.

The CDI specification has a "Programming Model" section. I like this terminology, but we should put it after a conceptual introduction to what we're doing (CDI kind of drops it on you).

Persistence

Jakarta Persistence is a beast of a specification and not entirely worth emulating. There are a few structural things in it that I think do make sense to incorporate.

The biggest is: it has sections that explicitly mention contracts and responsibilities and identify the roles involved. Our specification involves more roles than almost any other specification in Jakarta EE and many different areas that we may look to standardize. Making sure we clearly identify where the responsibilities and contracts are, and making sure those contracts and responsibilities show up prominently in the specification document, is very important.

Bean Validation

From a structural standpoint, I don't think there's much to use here, except for one thing. I like the "How this document is organized" section and its reminders that you have to read the whole thing.