Author: Edward Ervin, Financial Systems Product Owner for Global Switch and Community Captain.
Documentation isn’t often the task we look forward to. While we all recognise its importance, without the right tools, it can feel tedious and time-consuming. And it’s not just about writing things down - it’s about reaching users effectively and ensuring the information is accessible and easy to understand.
That said, documenting what you’ve built - and how to use it - isn’t just a nice-to-have; it’s essential. Without clear guidance, even the most brilliant solutions can become blockers, slowing progress and creating unnecessary frustration.
In this post, I’ll share some of the approaches I’ve used for documentation, the pros and cons of each, and why integrating Board and Scribe turned out to be the right choice for us - and why it made the documentation phase of our latest delivery something I didn’t dread.
Previous Solutions and Their Trade-offs
Before landing on the right approach, I experimented with several methods to make documentation more user-friendly. Each had its strengths - but also its limitations. Here are three examples:
1. Adding Labels and Text Directly on Screens in Board
This method involves placing instructions directly above or near the sections where users input data. It’s a common approach and seems practical, but it can quickly become cluttered when dealing with complex processes or multiple decision points
(Image 1: simple standardised workflow interface with text instructions)
- Pros:
- Quick and easy to implement.
- Instructions are visible where users need them.
- Cons:
- Users still need to navigate to the correct screen.
- Requires careful screen design to ensure logical step flow.
- Can lead to cluttered layouts and limited space for detailed guidance.
- Updating instructions can be cumbersome.
2. Creating Separate Documentation Pages or PDFs
Another approach is to create standalone documentation - PDFs or pages in tools like SharePoint or Confluence. This allows for detailed explanations but introduces friction.
- Pros:
- Plenty of space for detailed content and visuals.
- Easy to structure and organise.
- Can be shared widely across teams.
- Cons:
- Users must leave the application to access instructions.
- Harder to keep updated alongside system changes.
- Risk of outdated or forgotten documentation.
3. Creating RTF Cubes to Store and Edit Documentation Within Board
This is a more development-heavy solution. It involves creating RTF cubes dimensioned by screen and/or workflow task. You can then display documentation directly within Board using a button that opens a tab with the relevant content.
- Pros:
- High flexibility in user interaction.
- Seamless experience - documentation stays within the application.
- Users can access precise guides without searching.
- Cons:
- Time-consuming to set up.
- Requires ongoing maintenance of entities and cubes.
- Needs someone familiar with Board to manage documentation.
- Can become complex if workflows or screens change frequently.
Using Scribe for Documentation
- Scribe is a tool that captures workflows using annotated screenshots. It works on clicks - each click captures a step, and Scribe auto-generates annotations. Editing is straightforward, and the result is a clean, user-friendly guide.
- For quick guides, you can finish in under five minutes. For more polished, end-user-ready documentation, it might take 10 - 30 minutes per process - still a major improvement over traditional methods.
How to Use Scribe in Board
- Create a cube to store the embed code (a basic text cube works).
- Add a screen with a Web Viewer object linked to that cube.
- Select one intersection in the cube, and your document displays beautifully inside Board.
- Pro Tips:
- Zoom screenshots fully out before embedding.
- Set embed settings to Large for clarity.
- Use Slides for navigation, though Scrolling and Video modes are also available.
- Export options include Word, PDF, and more.
- Use Pages to combine multiple guides into one document - also embeddable.
(Image 2: Example Help Guide showing the user a full end to end process, embedded in a Webviewer – Step 4 in the process)
(Image 3: Example Help Guide showing the user a full end to end process, embedded in a Webviewer – Step 5 in the process)
(Image 4: Example Help Guide showing the user a full end to end process, embedded in a Webviewer – Step 6 in the process)
- Pros:
- Highly flexible and professional-looking.
- Easy to edit and maintain.
- Multiple sharing options: embed in Board, export, or share via link.
- Versioning is seamless—new versions save as copies, so embed codes remain valid.
- Built-in draft/publish workflow ensures users only see finalised content.
- Cons:
- Licensing required:
- Creator licence for editing and creating.
- Viewer licence for access (affordable, but still a factor).
- Some user-side tweaks needed, like enabling cookies to avoid frequent logins.
Final Thoughts
Integrating Board and Scribe has transformed how we approach documentation. It’s no longer a chore - it’s a streamlined, user-friendly process that enhances clarity and reduces friction. While no solution is perfect, this combination strikes a strong balance between usability, maintainability, and professionalism.
In the past, if I had adequate time, I would have opted for option 3 (RTF cubes within Board), and if not, option 2 (separate documentation pages or PDFs). However, this new method of integrating Scribe with Board enables many of the pros of both those methods - such as in-app guidance and rich, structured content - without the associated negatives like heavy development effort or fragmented user experience.
If you’re looking to improve your documentation workflow, I’d highly recommend exploring this integration. It might just change how your team feels about documentation too.
And whilst Scribe is the tool we found, there are alternatives out there. For our use case, however, Scribe offered the right support, the right features, and came in at an acceptable price point.
Have you used Scribe in conjunction with Board? If so, how was your Scribe experience?
