Technical Documents
There are basically two parts here, the first are the Use Cases which provide information on the scenarios we want to work on. And there are the Best Practices documents which describe how these scenarios are implemented.
Documentation review - Suggested rephrase of the preceding paragraph:
Technical Documents include:
- Use Cases describe scenarios where data portability will be useful.
- Best Practices describe how to implement the use cases.
End comment
These documents are maintained by the Technical Action Group.
Documentation review - the preceding sentence is non-priority to the reader - move to end of doc. - End comment
Use Cases
The Use Cases describe user scenarios we want to solve. Look in those to see what problems we identified and what might be missing (and add them).
Documentation review - the preceding paragraph has a number of issues:
First sentence is a waste of words if we include a section at the top of this section about the target audience and expected skillsets. Stating audience and skillset is a requirement for any good tech doc..
Second sentence - we read docs, not "look in" them. Suggest rephrase to "The Use Cases describe issues that users have related to data portability. This list is not comprehensive. If you are aware of other use cases, please add them to this section."
End comment
Best Practices Documentation
The central starting point for implementing DataPortability on your site are the Best Practices Documents. They describe what Use Cases they implement as well as how they implement them. They describe the use case in short and link to the complete description for reference.
They also describe the process of what a site has to do to implement the describes Best Practice. Additionally it links to Technical Specifications which are describe the choices for a certain technology or an implementation pattern in more detail.
Here is the list of Best Practices documents and their status:
Other documentation
