Why organize your documentation in multiple workspaces

10 May 2016

by Eric Kloster

Crossing ModelsWe have found that new users in Ardoq often are tempted to cram all their data into one workspace. Our recommendation is always to resist this temptation. There are a few practical reasons why one might want to spread data across multiple workspaces in Ardoq. I’ve listed them below.

  1. Permissions are set per workspace. If you want to deny certain users access to parts of your documentation, these parts have to be in separate workspaces, to which these unworthy users don’t have access.
  2. When sharing your documentation, different audiences might not want to see all of it at once. A board room might want a high level abstraction. An IT specialist might only be interested in the details. Spreading it across several workspaces allows you to give audiences an uncluttered view of the data that interests them.
  3. If you plan to automate any data import, it is a good idea to isolate the imported data in a workspace of its own. This is to avoid messing up all your documentation, should your automated import start getting buggy or if you have regrets about how you set up your import.
  4. If you are documenting different domains within your organization, it’s unlikely that there is a simple data model that can capture everything. We recommend creating several simple models rather than one crazy-complex model. If you want to involve others, domain specific models help domain professionals contribute without getting confused. Don’t forget that you can link between models.

On a general note, the purpose of documentation is to be consumed. For that to happen, documentation should be created in a way that has the reader in mind.

Context is necessary if anyone is to make sense of your documentation. However, anyone who doesn’t share the author’s insights into a particular domain and all its jargon, norms, notations, technology etc. might not know the context. Consider, therefore, workspaces in Ardoq to be similar to chapters in a book. The title and the structure of the chapter is the first indicator of what you are reading.

Relevant knowledge base articles: