Get in touch

BDQ Solutions

Lightning Implementations
For people who know what they want, and want it done fast
Enhancement Hours
Get best practice and configuration consultancy.
Review and Assessment
A low cost, low risk way to get the assistance you need.
Digital Adoption Services
Make sure software is being used consistently across teams.
PII Services
Our solution to help you find unauthorised data.
DevOps Services
Get great, high quality software shipped faster. Faster.
Test Automation & Management
Reduce costs and increase quality with automation.

    Atlassian Solutions

    Atlassian Enterprise
    SCALE WITH CONFIDENCE USING THE BENEFITS OF pREMIUM AND aCCESS
    Jira Work Management
    work management for technical & non-technical teams.
    Cloud Migration Services
    Quicker and more cost effective than doing it in house.
    Jira Service Management / ITSM
    Fast, painless, fixed price ITSM implementations.
    BDQ AtlassianCare
    Cost effective, flexible care options.
    Other Atlassian Services
    Maximise the potential of your Atlassian products.

      Other Solutions

      LEXZUR PRACTICE MANAGEMENT
      Complete managament software for legal practitioners.
      Asana Digital Work Management
      A simple, flexible way to manage work for business.
      Solutions Home

      Solutions

      Expert consulting and managed services to help complex organisations to work flatter, faster and more dynamically.

      With the help of our trusted partner:

      logo-gradient-blue-partner

       

        BDQ Originals

        EEASD_for_mega_menu_150x175

        BDQMAJC_for_mega_menu_150x175

          Other products

          Atlassian-vertical-blue@2x-rgb

          Sonatype_stacked_logo_full_color_150x150


            asana-colour-clear-300x300

            lexzur-logo-blue-strapline-1200x700

            zephyr-colour-clear-300x300

             

              Products

              Whether it's our own Atlassian Marketplace apps or the apps that we provide a value-added-reseller service for, you can trust BDQ for the best support, consultancy, training and implementation available.

              Reseller Details

              Products Home

               

                Training

                • We provide high quality technology training to customers in the UK, EU and US.

                • Our customers range from small companies to multi-nationals. They all want to maximise employee productivity.

                • We listen to what our customers want to achieve, and take this into account when delivering the courses.

                home-icon-300x300Training Home →

                  About Us

                  This is where you can find out all about BDQ. Where did we come from, what is our goal, what do our customers have to say about working with us? You'll find all those answers and more using the links here.

                  However, if you have any questions that you haven't found answers for, feel free to get in touch.

                   

                    13 min read

                    The Foundations of Good Documentation with K15t

                    Featured Image

                    As you may have read in our recent blog post, we have just released a new app for the Atlassian Marketplace called Easy Email Attachments for Service Desk, allowing users to send real mail attachments in customer notification emails from Jira Service Desk - simple and easy.

                    As part of releasing the app, we wanted to take another look at how BDQ approaches public documentation and put in a place a firm foundation for this app and others that we have planned for the future.

                    RTFM - Read The Fine* Manual. 
                    * Please note: Other words beginning with F may be used depending on the reader’s preference. 

                    The internet slang term RTFM suggests that a user should always refer to a product’s documentation before asking a support question. Excellent advice... but it requires the documentation to be easily accessible and good quality. 

                    We at BDQ take documentation seriously. From a consultancy project for a specific customer to a product release to a wider audience, we feel that a piece of work is not finished until it is clearly documented in an easily accessible fashion.

                    Past approaches and requirements

                    Over the years we, like many others, have approached the problem of public documentation in several ways.

                    At one time or another, we have used pages on the website, downloadable Word documents or PDFs, help files authored in tools like Help and Manual and public Spaces in Atlassian Confluence.

                    These options have their advantages and disadvantages, but we wanted to solve the following requirements:

                    • Be Agile

                    We embrace Agile in our development and testing process, but our previous documentation approaches did not support this particularly well.

                    In reality, writing the documentation was a follow-on, waterfall phase that happened towards the end of the project or release. We need a more agile approach, allowing us to change the documentation as the release progresses and then publish it in one go as the release progresses. 

                    We therefore needed the ability to edit documentation to add new content, revise or delete existing material across multiple pages, review it internally and then release the package of new documentation publicly in a single “drop”.

                    • Support multiple product versions simultaneously 

                    The products we are working on will have several releases over time as we develop our roadmap and respond to customer feedback. The solution we put in place must allow us to have older versions of the documentation available for customers on those previous versions. 

                    To support multiple versions of Atlassian’s products that have different APIs, we need to have multiple parallel versions of our apps. As far as possible, we keep the functionality between these parallel app versions the same, but it is possible that the API limitations may not allow this. We therefore will need to have documentation for each version. Maintaining this will require us to keep several similar pieces of similar content in step.

                    We did not want the solution to require us to have multiple copies of the documentation in different spaces. We have tried this approach before and found copying changes between spaces a bit of a chore and prone to mistakes. 

                    • Presentation is key

                    As any contestant on MasterChef knows, you can have great ingredients with the best of flavours, but lack of presentation can ruin a dish.

                    To make the experience of using the documentation better for our customers, our content must look great (good enough to eat?) and be easy to search.

                    • Long-term approach

                    We are developing several products, and we want all our documentation to be managed and delivered consistently, putting in place a firm foundation for the future. This will make it easier for our customers to find what they need, and it will be easier for us to maintain.

                     

                    K15t

                    In the Atlassian Marketplace, there is one vendor synonymous with documentation - K15t

                    Based in Stuttgart, the company’s products are used by over 5000 organisations worldwide to manage their content and documentation in Confluence. The Scroll Apps series of products enables teams to author, manage, and deliver documentation and technical content while leveraging all the collaborative muscle of Confluence. It makes documentation an agile process that keeps pace with development and fast-changing products and services.

                    After talking with K15t, they offered us some expert advice about which of their products would meet our requirements and how best to configure them in Confluence to meet our requirements: Scroll Versions and Scroll Viewport.

                    Scroll Versions

                    Not to be confused with the page history functionality built into Confluence, which is limited to recording the changes of individual pages, Scroll Versions adds comprehensive versioning control to whole Spaces. This versioning functionality is like branches within source control. 

                    Using this app, we can: 

                    • Create named versions of the documentation. 
                    • Compare content between versions.
                    • Merge changes spanning multiple pages between versions.

                    These capabilities address our first two requirements, allowing us to work in an Agile way and managing multiple product versions.

                    Scroll Viewport

                    To address the other two requirements, K15t suggested that we use Scroll Viewport.

                    This app allows the publishing of content within Confluence to a beautifully themed Help Centre, which includes easily accessible search available from the home page and at the top of every page. 

                    This screen capture shows how contents in Confluence is displayed in Scroll Viewport: 

                    Scroll Viewport

                    As we mentioned, presentation is key and the Help Centre Theme included in Scroll Viewport really looks great on every device - no more struggling on mobiles to see a desktop oriented page.

                    The theme is highly customizable, allowing us to brand the portal easily, but if required an entirely custom theme can be built using Velocity, HTML, CSS and Javascript.

                    While we did not need that option for our help centre, it is good to know that the option for a fully custom theme is available to us, if we wish to go in that direction in the future. 

                    The app home page in Scroll Viewport

                    When used in combination with Scroll Versions, Scroll Viewport is a powerful way to manage documentation and make it easily accessible to external users. Specific versions can marked as visible within the Viewport and they are then available to customers within the Help Centre from a version drop down menu.

                    Scroll Versions app - drop down menu

                    Another useful feature of the app is that it allows Global URL Redirects to be configured. This allows us to set up short links to content within the help centre or anywhere on the web. Sorry bit.ly, we might not need you so much in the future. 

                    Our setup

                    The rest of this post delves a little more deeply into how we configured the two products and the process we will follow to release new versions of the documentation, but first, let us talk about hosting. 

                    Hosting

                    Until relatively recently, the availability of Atlassian Marketplace apps was higher on Server rather than Cloud and so when we initially set up our Atlassian installation, we hosted them ourselves using Server running on AWS EC2 instances. 

                    However, app availability on Cloud has significantly increased over time and, if we were setting up our installation for the first time now, we would definitely consider Cloud to be the better option in many ways. Hosting, updates and security are handled by Atlassian, leaving customers to concentrate on actually “using” the products. 

                    Fortunately for customers who wish to replicate our documentation set up on Cloud, K15t has embraced all hosting options and recently released Scroll Viewport for Cloud to very impressive customer reviews. Additionally, Scroll Documents provides versioning functionality on Cloud similar to Scroll Versions.  

                    Scroll Versions

                    Due to using Scroll Viewport, the Scroll Versions Publishing functionality is not required. Instead, we followed K15t’s Integrate with Scroll Versions documentation. Specifically, the integration allows to author new versions privately and make them publicly available in the Viewport at once.

                    Scroll Versions versions list - shows visible in Viewport icon

                    As mentioned in our requirements, we must support two parallel versions of our  product to handle difference in the Atlassian API between version 3.x and 4.x of Jira Service Desk. 

                    In the version setup, we created an initial “First-Version". Off this, we created new versions called "3.0.0" and "4.0.0" and made them visible via the Viewport (see below for how that was configured). 

                    We then created two additional versions called "Next-REL3" and "Next-REL4". Documentation changes for later versions will be mostly made in "Next-REL3" and merged into "Next-REL4", with only "4.0.0" specific changes being made in that "branch".

                    Initial hierarchy of versions diagram

                    This configuration looks like this in the app:

                    Scroll Versions list of versions

                    Creating new releases of documentation follows these steps: 

                    • Merge Next-REL3 with Next-REL4

                      • Go to Space Tools > Scroll Add-ons

                      • Select Scroll Versions > Versions

                      • From the list of Versions select "Merge" from the Actions menu of Next-REL3.

                      • Merge into Next-REL4.

                    • Rename Next-REL3 and Next-REL4 to the version number of the new releases

                      • From the list of Versions select "Edit" from the Actions menu of the Next-RELx.

                      • Change the name to the version number 3.x.y or 4.x.y

                      • Change the colour and set the Release Date.

                    • Create new Next-RELx versions.

                      • Press the "New version" button

                      • Name the version Next-REL3 or Next-REL4.

                      • Select the correct Preceding Version. 

                      • Set the Color to gray. This represents that the version is not visible in the viewport.

                    • Stop edits in the new releases

                      • To prevent edits we apply edit restrictions to a Confluence user group called bdq-none - a group contains no users. See How can I lock version editing after publish?

                      • From the Action menu select "Manage restrictions".

                      • Add the group "bdq-none".

                      • Press the Save button. 

                    • Display the release versions in the Viewport

                      • From the Actions menu select "Show in Scroll Viewport" next to the 3.x.y release.

                      • Repeat for the other release 4.x.y.

                    • Verify that the documentation is visible via the Help Centre from an Incognito browser window. 

                    This diagrams shows how the versions described interrelate following the steps above:

                    Diagram showing hierarchy of versions after next release

                    Scroll Viewport

                    To support future apps, we have used the approach described in Structure Your Help Center to create a multi-space help centre. This requires setting up the following spaces. 

                    • Portal space

                      • This root space contains no actual content and is used to put text on the help centre home page via an Excerpt macro on the space home page.

                      • In the Scroll Viewport settings for this space, we set the viewport up as a “Viewport Collection”. This means that any viewports that have the same path are grouped together under the portal space. See Group Viewports in a Collection.

                    • Member space

                      • One of these is created per product and contains the documentation for that product. 

                      • The layout that we use for this space is the Detail layout and not the Hero layout. This is controlled by a setting called spaceHomePage.layout in the overall Help Center theme. The image used to represent the space in the theme is the Space logo. 

                      • Call to Action Button at the top of the page is controlled by the Confluence label: scroll-help-centre-cta-page.

                      • Pinned pages are selected using the labels scroll-help-center-pinned-page-1, scroll-help-center-pinned-page-2 and scroll-help-center-pinned-page-3. The text displayed on the Member Space page is by using an Excerpt macro.

                      • News pages are selected using the label scroll-help-center-news-page. Up to three pages are displayed.

                    The relationships between the spaces are as follows:

                    Scroll Viewport - hierachy of spaces

                    In order for the documentation to be visible to non-logged-in users, the spaces must allow Anonymous access to view the pages only. 

                    Conclusion

                    Without any hesitation we would recommend both Scroll Versions and Scroll Viewport to anyone who wishes to manage anything other than the most simple public documentation within Confluence. They will be the foundation of RTFM-able documentation for us for the foreseeable future.