Outdated Content!
The Protocols and Formats Working Group is no longer chartered to operate. Its work will continue in two new Working Groups:
- https://www.w3.org/WAI/APA/ Accessible Platform Architectures, to review specifications, develop technical support materials, collaborate with other Working Groups on technology accessibility, and coordinate harmonized accessibility strategies within W3C; and
- https://www.w3.org/WAI/ARIA/ Accessible Rich Internet Applications, to continue development of the Accessible Rich Internet Applications (WAI-ARIA) suite of technologies and other technical specifications when needed to bridge known gaps.
Resources from the PFWG remain available to support long-term institutional memory, but this information is of historical value only.
This Wiki page was edited by participants of the Protocols and Formats Working Group. It does not necessarily represent consensus and it may have incorrect information or information that is not supported by other Working Group participants, WAI, or W3C. It may also have some very useful information.
Introduction Guidelines
From Protocols and Formats Working Group Wiki
Here are some suggestions to help craft good introductions:
- An introduction should target an audience that has general technical literacy but not in-depth background in the area of technology the spec addresses. Even in a technical specification, the introduction should be as minimally technical as possible. The rest of the spec is for that.
- Where it is deemed necessary to explain technical matters, the content should start simple to lay a basic understanding, and then move to the technical stuff.
- The introduction shouldn't make too many assumptions about a reader's background knowledge. Especially where a spec indicates dependency on other technologies, knowledge of those technologies should not be taken for granted, and a brief explanation is warranted. We can't take this to an extreme and painstakingly explain stuff that "everybody knows" but we have to expect readers don't know everything we do.
- Introductions should explain the problem the specification exists to solve. This is, to some extent, explaining requirements, and it's helpful to point to the requirements document.
- The introduction should explain, in general terms, how the spec solves the problem. It would explain the basic approach.
- In some cases it's useful to explain why the approach is better than others that were considered, but often that might be more confusing than helpful.
- Introductions should not include specification language or implementation guidance. That content belongs elsewhere in the spec.
- Examples of how an implementation would work are very helpful. These can be use cases, diagrams, mock-ups, etc. Code examples are less helpful for an introduction, and are mainly of value in the normative parts of the spec. If code examples are included, they should follow and clearly grow out of the more "hand-waving" examples.
- An introduction should clearly say who would implement the spec, and why.
- The introduction should explain the benefits of implementing the spec (both to implementers and to other stakeholders), and the costs to not implementing it.
- In spite of all that, the introduction shouldn't be too long. It needs to introduce the spec effectively but not bog down the reader. 300 to 500 words would be optimal for a shorter specification. A longer spec might need a longer introduction, but it should be kept as short as realistic to meet its goals.
Notes from 13 Aug 2014 PF call
- re-order to group concepts
- add how this spec relates to other docs