BestPracticesForBPDocs
From oaibp
Contents |
[edit] Best Practices for Best Practices Documents
[edit] Context
- Give context, motivation, justification for requirements and recommendations
- Explain WHY and HOW practices are useful, both generally and with specific examples.
- Indicate downstream implications
- State tradeoffs
- Be example rich and use examples from multiple domains (see below)
- Present common pitfalls
- Indicate worst practices when helpful
[edit] Prescriptiveness
- Be as prescriptive as possible but be aware of domain differences
- Use examples to illustrate prescriptiveness
[edit] Re-use previous work and use standards
- Encourage re-use of existing solutions
- Recommend standards, even multiple standards
- Be Link rich (to tools, papers, documents) - don't reinvent the wheel!
[edit] Modularize!
- Allow a variety of entry points
- Allow good cross linking
[edit] Make it readable, user friendly
- Think of target audience
- Good flow
- Avoid jargon (use the OA Forum glossary whenever possible
[edit] Example Formats
Examples within wiki pages should:
- be expressed in xml where possible;
- be in at least two metadata formats for the metadata content section;
- be in snippets within the wiki (because of the problems of expressing xml in the wiki);
- have a link to a full example loaded as a separate document within the wiki (see below).
- be numbered consistently within a specific page. See the DeletedRecords page for an example.
Full examples should be distinct documents (a variety of files, including xml, are supported) loaded on to the wiki. To load documents simply log in and go to the Project File List. If you are logged in, you should see a link to upload new files.
Because full examples may be reused in different sections of the wiki (how many seperate Identify responses do we want to include?), the name and description of the file should reflect its content. When these full records are used within the wiki, however, they may be renamed. For example, the file named IdentifyResponse_Best_1.xml (Example of an Identify response) has been named Deleted Record Example 1 in XML on the DeletedRecords page by using the bracket labeling convention.
A list of all of the full examples is maintained on the Table of Contents page of the wiki. Whenever a full example document is loaded, it should be added here with a brief description.
