Modeling

The following documents explores how requirements can be translated into a PageSeeder solution using the following tools:

  • Use cases – conventional use case models can be 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 can be useful for understanding how to configure groups and projects.

Prototyping

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 is 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 the following PageSeeder objects are easy to edit, they will help to keep the cost and time required to prototypes down:

  • Built-in document types (e.g. default and references)
  • Labels – document, section, paragraph and others

Iterate

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 easy 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:

Identifying members

Use cases should provide a list of actors

  • 1 actor = 1 member account

If auditability or security is important, create a member for

  • 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 will benefit from knowing who performed the task. Examples of this are: 

  • creating a document,
  • edit a document,
  • post a comments,
  • create, or advance, a task,
  • create a document version.

Identifying groups

Groups can be used to filter content. They are also a way to logically group members.

  1. Do not put members in the same group if they cannot view the same data (document, comment, etc.)
  2. Bear in mind that
    • Members can belong to several groups
    • Everyone in a group can view the data
    • Data can be shared between groups
  3. Consider personal groups to store information specific to a member
  4. Consider subgroups to make group administration easier

Designing groups

Roles filter functionality.

  1. Assigns roles to members to reflect their permissions
    • Reviewer to view the documents and comments
    • Contributors to edit and manage documents
    • Etc.
  2. Limit the number of system administrators
  3. Group properties after your have designed the project properties

Identifying projects

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.

Identifying URIs

Use URIs for...

  • 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

Organizing documents

Documents can be organized using

  • Folders
  • XRefs (i.e. through “master” documents)
  • Document labels
  • Document types

Consider folders when

  • There is a clear hierarchy
  • There is a logical mapping to the file system

XRefs

Use Xrefs to connect documents together

  • XRefs are often used to express a relationship

When using XRefs consider:

  • Scalability (too many XRefs from one end-point)
  • Permissions when cross referencing across groups
  • Organizing documents

Labels vs. type

Consider labels when

  • There is no specific structure associated with the document
  • Multiple labels can be applied to a document

Warning!

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

Warning!

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

Identifiers

  • URI ID is a system identifier
  • Doc ID is a public identifier

Semantics

  • 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

Structure

  • Provided through document and section templates

Validation Rules

  • To apply domain specific constraints

Identifying tasks and comments

  1. Use comments for basic content
  2. Use tasks for basic workflows
    • Which can be simply expressed with a status, priority, due date or assignment
  3. Remember that tasks and comments have semantics too
    • Comment labels

Next...

Let's now have a look at some common patterns that can be used in PageSeeder to make modelling easier.

Created on , last edited on