...
- Is there a definition of Activity Streams including the context of their usage? Probably should be clearly in the Overview, in Architecture, and defined under terminology. Where to include a link to official activity stream documentation? Recommended to consider putting at the top of section 3 describing Organizational Structures. Intro paragraph between 3. Organizational Structures and 3.1 Entry Point.
- Move Objectives and Scope ahead of Use Cases
- Double check links from descriptive paragraphs to official Activity Stream docs. They don't seem to be in the text. Minimally at the start of sections where they are used. For example, link to Ordered Collection from the start of 3.1 Entry Point, and to Ordered Collection Page from the start of 3.2 Change Set.
- Will the doc be read sequentially or jumping around randomly? If sequentially, then top of section makes sense. If randomly, maybe consolidate in terminology as opposed to including at every mention of the term. So maybe a combo of these two approaches.
- Add as Reference at top of each major section. E.g. Reference: Ordered Collections at top of Entry Point.
- Concepts vs. Implementation specific terms (i.e. Entry Point vs. Ordered Collection)
- How will people talk about it? The way we express it may be how people will talk about it.
- Entry point may drop into a longer running stream.
- Want this to be easy to understand for those who already know activity streams.
- Entity patch, is that a generic term, or are we really talking about RDF Patch?
- When introducing a section, if we want to recommend a particular technology, it would be good to be clear about that at the start of the impacted section.
- Doc should support...
- close sequential reading - try to avoid including links every time a concept is mentioned
- scanning - include good headings
- keyword search - include keywords in each section where they apply to enable finding that section
- Move section 6. Consuming Entity Change Sets to section 7. And make section 6. Producing Entity Change Sets
- Diagram
- Is this an ER diagram? If yes...
- Each rectangle is seen as a set, so wondering why are there 3 boxes for Change Set? In this diagram, the 3 Change Set boxes are showing how first, next/prev, and last work?
- Why 3 rectangles for each Entity Change Notification? Probably switch to one box.
- Maybe add 1..m cardinality indications for each box
- Is this an ER diagram? If yes...
...