This document explores how requirements can be translated into a PageSeeder solution using the following tools:
- Use cases – conventional use case models are a useful mechanism to identify members and their relationship to groups (membership).
- Semantic data model – objects such as entities, attributes and relationships are often a good way to represent URIs, XLinks and groups. It can also be a useful way to represent constraints.
- System requirements – these are useful for understanding how to configure groups and projects.
Modeling a PageSeeder implementation is a really useful way to test the logic and functionality of a solution. An effective way of doing this is by iterative prototyping or a ‘trial-and-error’ approach. Implementing trial solutions using minimal customization can be a practical and meaningful way to document a specification.
However, getting the most out of prototyping requires an understanding of the relative cost of implementing PageSeeder objects. Just as, effectively renovating a building requires the knowledge that it’s more expensive to move a wall than it is to paint it. For this reason, the following aspects should be carefully considered before putting into production.
Expensive to change
The following PageSeeder objects are relatively more expensive to change once the system is in production, therefore, should be fully proven in the prototype.
- Fragments – where order, ID or templates are concerned, making changes is hard.
- Custom documents types.
- Group and project names.
Inexpensive to use
Because these PageSeeder objects are straightforward to edit, they help to keep the cost and time required to prototypes down:
- Built-in document types (for example, default and references).
- Labels – document, section, paragraph and others.
Build a comprehensive proof of concept—be prepared to throw it away. As most developers already know—nothing is as simple as it seems .
Then, crystallize constraints into more rigid structures
It’s not difficult to shift markup, but all structure should exist in some form. Markup that prototypes quickly, like a paragraph label or even a ‘bold’ format, can be changed to something more permanent in production. Examples of more permanent objects are the following:
Use cases should provide a list of actors:
- 1 actor = 1 member account
If auditability or security is important, create a member for the following:
- Every system connecting to PageSeeder.
- Every user interacting with the system.
Remember that every XLink is associated with a member, making them a good device for any task that benefits from knowing who performed the task. Examples of this are:
- Create a document.
- Edit a document.
- Post a comment.
- Create, or advance, a task.
- Create a document version.
Groups can be used to filter content. They are also a way to logically group members.
- Don’t put members in the same group if they cannot view the same data (for example, document, comment).
- Bear in mind that:
- Members can belong to several groups.
- Everyone in a group can view the data.
- Data can be shared between groups.
Roles filter functionality.
- Assign roles to members to reflect their permissions, for example:
- Reviewer – to view the documents and comments.
- Contributor – to edit and manage documents.
Projects act as main configuration points. If groups share the same configuration, they should be part of the same projects.
Projects can be used for organizing groups logically, but they must be able to share the same configuration.
Use URIs for the following:
- Any file stored on the file system.
- Any data which has structured content.
- Any data which requires sophisticated semantics.
- Any data that needs to be edited.
- Any data that needs to be imported, uploaded or exported.
- Any data that requires validation.
Documents can be organized using the following:
Consider folders when:
- There is a clear hierarchy.
- There is a logical mapping to the file system.
Use Xrefs to connect documents together:
- Xrefs are often used to express a relationship.
When using xrefs, consider these:
- Scalability (too many xrefs from one endpoint).
- Permissions when cross referencing across groups.
- Organizing documents.
Labels versus type
Consider labels when:
- There is no specific structure associated with the document.
- Multiple labels can be applied to a document.
Labels can be very useful to classify documents, but they are not always published!
Use types when:
- There is a specific structure for the document.
- Document types are mutually exclusive.
Types are immutable in practice. It is difficult to change the type of a document: it requires the help of a developer to download the document, edit it manually and upload the document with the overwrite option.
Designing PSML documents
- URI ID is a system identifier.
- DocID is a public identifier.
- Built-in standard semantics with PSML.
- Headings, paragraphs, etc.
- Problem domain specific semantics with content labels.
- Inline and block labels.
- Document type.
- Labels on document and sections.
- Provided through document and section templates.
- To apply domain specific constraints.
Identifying tasks and comments
- Use comments for basic content.
- Use tasks for basic workflows:
- Which can be expressed with a status, priority, due date or assignment.
- Comment labels.
Let us now have a look at some common patterns that can be used in PageSeeder to make modeling easier.