Are there any recommendations how to create/manage a documentation with branding
Hey there,
I am using Scroll Versions, Scroll Viewport and Scroll Translation for the online documentation of a software product (German and English).
Moreover, I am using Scroll PDF Exporter and Scroll HTML Exporter to generate PDF files and HTML files for the same product documentation.
Now the software product will be branded. So the branded product will show a different product name and a different company name. For instance, "Ax" should be displayed instead of the usual product name "A" and "Bx" should be displayed instead of the usual company name "B".
The product documentation should be branded as well. I am wondering whether there is a best practice for this?
Of course, the usual product documentation as well as the branded product documentation should be provided as fast (= automated) as possible. And for each monthly release as well.
I have already prepared the articles for our usual product documentation as follows:
The usual product name and the usual company name is specified within separate articles within the "_InclusionLibrary". Whenever the product name and the company name is quoted in an article, I am using the macro "Include+" to include the specific article with the product or company name. So I am able to quickly replace the product and company names for the usual product documentation.
But I am unsure about the best way to regularly create a branded product documentation.
I thought to publish the usual product documentation (the normal space) into a separate space and to change the product and company names in this separate space. Then the PFD-files and HTML-files will be created from this separate space with the changed names.
Would I need to manually change the product and company names for each release? Is it possible to change the product and company names in an automated mode? Or is it possible to keep the changed names (for the next published documentation)?
If you have any experiences with branded product documentation and its maintenance, I would be very grateful for your insights.
Cheers,
Eva
-
Hey there again,
I just remembered that I forgot the obvious approach: Of course, I can use the variant feature of Scroll Versions.
So for example, the variant "product-A" will be the usual product documentation and the variant "product-B" will be the branded product documentation. I will have to edit the articles with the product name and company name so that both names are specified in the articles, each name is inserted by using the macro "Conditional Content". Then I can simply switch between the variants when generating the different documentation.
But if there are any other methods or ideas for the branding of the documentation, I would appreciate your comments.
Cheers,
Eva -
Hey Eva,
did work out something? We are also looking for an easy solution for a whitelabel product. Working with the Conditional Content plugin works but is very, very cumbersome especially when it's inline as it does only work sometimes to keep or avoid line breaks. Also it looks extremely cluttered.
Maybe you worked out a different solution you are able to share?
Best,
Flo
-
Hi Florian,
we decided on using the variant feature. But we are not very "heavy" users - at least at the moment.
One major drawback is that it is not possible to customize page titles. As you have already discovered yourself - see your posting https://k15t.zendesk.com/hc/en-us/community/posts/360050524191-Variants-and-page-titles
I think I have even created a support ticket asking about the possibility about customizing the page titles. If I remember correctly, this is a restriction of Confluence itself (rather than of Scroll Versions).Anyway: We have decided on using a neutral phrase in the page title, such as "the application" (instead of the specific product name or the macro). I am not very happy about this approach.
But otherwise the variant feature saves a lot of time. Of course, it takes some discipline when writing the texts (for example to not copy and paste a text but to use the appropriate macro). But whenever a text modification or a new variant is required, I am quite glad that we are using the macros.
I hope this helps you.Cheers,
Eva -
Hi Eva,
thanks a lot for your quick reply. I see what you mean.
We are currently trying to migrate a working system for the publishing of documentation over to Confluence but it seems that it is not really possible without changing a lot of the workflow and content due to the various limitations (page title, page key (CHM exporter), macro cluttering).
Let's see if there might be a possibility for us. I really like the versions and translation integration but the variant integration is unfortunately a bit weak which might as you said be related to Confluence itself.
Maybe someone of K15t can add something to this topic (or confirm that it's a limitation).
Best,
Flo
-
Hi Florian.
It's not possible to have a dynamic page title with Variants, but you can use Conditional Content macros to replace certain words on a page.
I would suggest creating separate page trees for different variants. Or alternatively, thinking about generic page titles that would fit all variants.
If you have further questions, please let me know.
Roman.
Please sign in to leave a comment.
Comments
5 comments