How to Model a Documentation Page

Sample design

For the purpose of this article we're going to use this mockup – it contains a few elements typical to a Knowledge Base/Documentation page.

Example of a Knowledge Base/Documentation article page (here our own Technical Doc at Prismic):

Start with your design

Navigate between the static and dynamic zones of the custom type to follow the steps that explain how to build this example documentation page:

Static Fields
Dynamic Zone

Article Main Title

Every page that we create will have a title at the top. We will model this using a TItle field.

1 of 7
< PreviousNext >

Article Author (optional)

You can attach a link to the author of the current article's biography. You will need to use a Content Relationship field that fetches the corresponding author page.

2 of 7
< PreviousNext >

Paragraph Block

This will consist of a Rich Text field to allow the authors to add their text content.

3 of 7
< PreviousNext >

Code Snippet Block

This will consist of Rich Text field for the code snippet text.

4 of 7
< PreviousNext >

Highlighted Text Block

Here we will use a Text field for the title and another Text field for the main text.

5 of 7
< PreviousNext >

Full-width Image

This will consist of an Image field to allow the content author to upload and select the image.

6 of 7
< PreviousNext >

Headline + text + image

This will consist of 2 fields: a Title field for the heading and a Rich Text for the paragraph (same as previously). But this time we will also need an Image field.

7 of 7
< PreviousNext >

You can save your Slices in the Slice Library to reuse them on other pages of your website and on other projects.

The content model

Selected approach: independent components, everything dynamic. Thinking about future documentation articles which can be composed of these components, it's clear that their order can vary from page to page, and some of these sections can appear multiple times. This means that each section is an independent component, so each should be modeled as a separate dynamic section. This way content managers will be able to construct new documentation articles in the future, reusing these components as they see fit.

Alternative approach: everything static. The first instinct is to probably set up the model exactly replicating the design: a single rigid structure with 3 components. There's nothing wrong with that, of course – until you need to create another documentation article with a slightly different structure (2 "code snippet" blocks instead of 1, for example).

Possible consequences of "staticness". If this entire page had been set up as a static section, then it would be necessary to create a new content model for each new documentation article to come, which would be suboptimal, to say the least.

Here are the 5 components you will need:

  1. Paragraph block
  2. Code snippet block
  3. Highlighted text block
  4. Full-width image block
  5. Image+Text block

These 5 blocks or components will be set up in the Dynamic Section so that they can be freely mixed and matched to build your documentation pages.

See the introduction to content modeling for more context on dynamic and static sections.

How to set it up in Prismic

  • Set up a new custom type
  • Add the fields for the static zone
  • For each of the 5 content blocks, create a separate slice
  • Add the field(s) for each slice as defined above

If you want to try this Knowledge Base/Documentation page Custom Type in Prismic, copy and paste the following JSON in the JSON editor in the top-right corner of your Custom Type as showed in the GIF below.

JSON structure


What editors will see

When an editor creates a document based on the documentation page custom type created above, they can add any of these slices and fill the placeholders with content.

How to model content for your project Sarah will be glad to help you come up with a solid content model for your project. (It’s free.) Schedule a call