Splitting the architecture document

[egekorkan]

Currently, the architecture document serves multiple purposes and in a way has different importance per section(s).

• Section 5,6 (horizontals and verticals) explain possible ways to use WoT. These sections are self contained, do not contain any assertion and other specifications do not depend on these sections.
• Section 8, 9 and partly 10 explain building blocks and architectural elements of the W3C WoT. These sections are normative and contain many assertions as found in preparing implementation report #624 . The first assertion of the spec is in section 8, a bit weird for a normative specification.

Note: Part below is entirely my opinion

The problem is that this makes it difficult to read the document or to use it as a reference in other specifications we have. Reading from the start, I am met with lots of information I already know, which are mostly marketing-like parts to convince that WoT can be used in multiple verticals and horizontals. This can be causing the misalignment between the specifications: editors are not that interested in reading this initial part or are saturated with information that they don't read the rest of the specification, which actually contains the assertions that they should be interested in when building their specifications. I think that this is the reason behind #625, #619, #412, w3c/wot-discovery#190.

I think that these should be actually different documents or very clearly separated in one document. Also for newcomers who just want to get right into specifics of WoT, this can be annoying, i.e. sifting through that promotion-like material to read the actual specification.

[mlagally]

@egekorkan , many thanks for your extensive review and your opinion.

For us, as the spec editors it is quite natural that we reread information that we already know in various areas of the WoT specifications.

However this is not the situation of the occasional / first time reader:
As we all agree, the architecture spec is the entry point to explain terminology, concepts, information model, deployment scenarios. The first time reader should be considered our primary customer, since he wants to understand WoT and potentially will decide whether he actually wants to use it for his products.

This should be our guiding principle when we consider specification improvements.
I'm already concerned about recent splits of the binding template document into smaller pieces - these potentially just cause additional editorial work and might cause confusion for readers.

[egekorkan]

The first time reader should be considered our primary customer, since he wants to understand WoT and potentially will decide whether he actually wants to use it for his products.

I agree but what if they already know about WoT? I still think that even for a first-time reader, there is too much text before they can get into the actual specification. This is just my opinion.

I'm already concerned about recent splits of the binding template document into smaller pieces - these potentially just cause additional editorial work and might cause confusion for readers.

You should open an issue about this or express your concerns in one of the many calls this was mentioned. We are talking about this for almost a year.

[mlagally]

Won't do for the 1.1 version.
We should create a new issue for 2.0, if needed.