When documenting an application with an interface, you always want to make sure to write clearly and concisely, but adding visuals like screenshots, diagrams, videos, GIF, etc. is important for context and to help illustrate what you’re explaining.
However, these visuals need to be updated when their associated documentation is updated, and this has been one of the more time-consuming burdens of documentation writing. And the more visuals used in documentation, the more time-consuming this process can be.
And as someone who has read a lot of different documentation, there’s nothing more frustrating than following instructions with icons, screenshots, etc. and then realizing that they no longer apply to the current version you’re using.
Throughout Nuxeo Documentation, we’ve included approximately 9,000 screenshots to help our readers better understand the concepts and use cases of our Content Services Platform. So every time we update our UI, we have to go through a massive update process to make sure that the screenshots are current so that we don’t confuse our readers. And I’m proud to say that our UI/UX improved a lot over the past few years!
Screenshot Management: Before
Until a few months ago, our screenshots were stored in our GitHub Documentation repository and we were using Git LFS to manage those large files. So every time our UI/UX changed (basically, at every quarterly product release), we had to update all the screenshots - on each related version and on each documentation type (technical, functional, tutorials, etc.). If the screenshots were renamed, we had to update the names throughout the documentation.
After many product releases and hours spent on updating the screenshots, we determined that it was time to improve our screenshot management process. And what better way to manage this than with the most modern and innovative Content Services Platform (CSP) on the market - ours!
Screenshot Management: After
Since nearly all Nuxeo employees collaborate on the documentation, we made it easy to use and maintain. We started by creating a custom document type in Nuxeo Studio with specific metadata attributes defined - such as the product, the version in which the asset was taken, the nature of it (screenshot, schema, gif, etc.), a description, etc. We also created a specific search for this document type so that users can check if the screenshot needs to be updated at a glance.
For this document type, we added a script that generates a unique ID that can be used on the associated documentation pages. It looks like this:
{{!-- ### nx_assets ###
path: /default-domain/workspaces/Product Management/Documentation/Documentation Screenshots/Studio/NOS/Connect Application Edited
name: CONNECT-application-edited.png
studio_modeler#screenshot#up_to_date
--}}
The last step was to connect our platform to the documentation website, so that every time the documentation build is restarted (this occurs once a day automatically), it checks if the screenshots have been updated since the last restart, and if so, it then displays the updated ones accordingly.
To do so, the code fetches each screenshot’s metadata referenced by the documentation and then fetches the corresponding blob.
What’s Next?
The next step is to migrate the existing screenshots to our platform and convert them to our custom doc type, and to keep improving the way we retrieve those assets to accelerate the build duration. For the latter, we plan to fetch a manifest of all the assets at once and simply link to where the asset is stored in S3.
Then, we’ll extend our usage to unlock the full benefits of Nuxeo Digital Asset Management for managing screenshots: automated resizing, watermarking, automated quality controls, and alerts.
There’s many more new features coming soon to our Documentation website, so stay tuned for more updates. And as always, we’d love your feedback!
Manon is the Lead Technical Writer at Nuxeo. Watch this to spend one minute with Manon.