Using Scroll Viewport for product documentation

kko...@stiltsoft.com

unread,

Apr 20, 2018, 7:21:15 AM4/20/18

to Scroll Viewport Developers

Hi there,

I have two questions:

1. We would like to create documentation using Scroll Viewport for a product that is available in two hosting options - Cloud and Server. Basically we need 2 sets of documentation articles. Something similar to what you guys have in your own HelpCenter. How do we accomplish this? I mean do we need to use the Variants feature of the Scroll Versions app to create two variants 'Cloud' and 'Server'? Or can this be done by using the Versions feature of the Scroll Versions app? Can you direct me to the recipe for creating a switch button to switch between Cloud and Server versions?

2. I will describe a case. Both Cloud and Server versions of documentation have a root page. A person is viewing an Article A in the Cloud version. Then switches to the Server version. We want that person to see Article A of the Server version, not a root page of the Server version. How to accomplish this?

Kind regards,

Katerina

Steffen Burzlaff (K15t Software)

unread,

Apr 20, 2018, 9:25:29 AM4/20/18

to Scroll Viewport Developers

Hi Katerina,

is your content saved in one space or are we talking about two spaces ( one per variant )?

Unfortunately, we do not have a recipe for such a switch button.

However, if you are working within one space, the right approach would be to create a variant for you cloud documentation. ( Read here how to do this ).

In Scroll Viewport you would have to implement a Versionspicker which will get activated if there are Versions of the selected Variant. Your Variants would only be a button.

So what your Version- / Variantpicker needs to check is the following:

Am I in the Variant Cloud?

If yes

show cloud button as selected
only a button to server variant

If no (I am on the server variant)

show the cloud button unselected
Replace Server Variant Button with Versionpicker

How to integrate Scroll Versions into Viewport you can read here.

The Code would be something like this:

#if($variants.current == "Cloud") 
{
  <div class="buttonGroup">
    <button class="variantPicker active">Cloud</button>
    <button class="variantPicker"><a href="link zur server variant">Server</a></button>
  </div>}
else 
{
  <div class="buttonGroup">
    <button class="variantPicker">Cloud</button>
    <select class="variantPicker active">
       #foreach($version in $versions.available)           <option value="$version.value"
           #if($version.name == $versions.current.name) selected="selected" #end
           data-version-accessible="$version.isAccessible">$version.name#*
           *##if($version.value == 'latest' && $version.original) ($version.original.name)#end#*
           *#</option>
       #end
    </select>
  </div>
}

Please keep in mind that this is probably not a fully working version, but gives you an idea what you need to do.

Let me know if this helped you.

Best,

Steffen

Katerina Kolina

unread,

Apr 20, 2018, 10:31:41 AM4/20/18

to scroll-vi...@googlegroups.com

Hi Steffen,

Thank you very much for your quick reply and your help. The Cloud version of the product is not released yet. So we don't have its documentation yet and can choose any option - use one or separate spaces for Cloud and Server docs.

As I understood, the variant feature is needed if we use the same space.

What if we decide to use two different spaces? Is it still possible somehow? Is there an approach without using variants in our case?

We are considering several options and would like to find one that covers our UI goals and easy to support.

One of the options is the following. Don't have several versions for the Server docs. Simply one version of Cloud and one of Server.

Do I understand it correctly?:

in this scenario I would need to have one (or two - if I don't use variants) private spaces
when I need to make changes, I create a new version in a private space
when done, I will publish changes to an existing public space

In case we use multiple versions for Server docs, I suppose I will have to publish each new doc version to a new space and modify the viewport theme by adding a new viewport - to have it in the version picker of a switcher.

Is it correct?

What about the second question in my first message?

I will describe a case. Both Cloud and Server versions of documentation have a root (landing) page. A person is viewing an Article A in the Cloud version. Then switches to the Server version. We want that person to see Article A of the Server version, not a root page of the Server version. How to accomplish this?

Best wishes,

Katerina Kolina
Business Analyst
email: kko...@stiltsoft.com

Check out StiltSoft add-ons for Atlassian products

--
You received this message because you are subscribed to the Google Groups "Scroll Viewport Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to scroll-viewport-dev+unsub...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/scroll-viewport-dev/86ece483-ad3f-4bce-a643-9580d9b16637%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

Steffen Burzlaff (K15t Software)

unread,

Apr 23, 2018, 3:00:37 AM4/23/18

to Scroll Viewport Developers

Hi Katerina,

I will describe a case. Both Cloud and Server versions of documentation have a root (landing) page. A person is viewing an Article A in the Cloud version. Then switches to the Server version. We want that person to see Article A of the Server version, not a root page of the Server version. How to accomplish this?

Variants already cover this scenario. If you have a page A in the variant "cloud" and switch the variant to "server", you still stay on page A.

What if we decide to use two different spaces? Is it still possible somehow? Is there an approach without using variants in our case?

If you use two different spaces, of course, you are able to switch to the other 'variant'. You wouldn't have to use variants in this case, but I would recommend it due to the URL naming pattern.

You would need to publish the space in another existing space. In this space, you would have to activate also a viewport and in your button just needs to link this space. The downside of this approach is, that

you can't switch from page A cloud to page A server, out of the box.

Don't have several versions for the Server docs. Simply one version of Cloud and one of Server.

If you only need one version for each variant, then I would recommend to just use variants, since the version would always be "latest", which doesn't really make sense.

Also If you would only use variants, you could use one space and benefit from of the "page A to page A" out of the box function.

in this scenario I would need to have one (or two - if I don't use variants) private spaces
when I need to make changes, I create a new version in a private space
when done, I will publish changes to an existing public space

If you don't want to use variants, then yes I would recommend to split it into two spaces. With the other two points, you are correct. ( also in our documentation )

In case we use multiple versions for Server docs, I suppose I will have to publish each new doc version to a new space and modify the viewport theme by adding a new viewport - to have it in the version picker of a switcher.
Is it correct?

Yes at the moment it is not possible, to publish into spaces where Scroll Versions is active. ( https://k15t.jira.com/browse/VSN-2054 ) Please feel free to upvote, watch or comment this issue. If you want this issue, you receive updates if the status of the issue changes.

I hope this will answer your questions. If there are still some open questions, feel free to ask.

Thanks and have a nice day.

Best,

Steffen

Katerina Kolina

unread,

Apr 23, 2018, 5:48:56 AM4/23/18

to scroll-vi...@googlegroups.com

Hi Steffen,

Thank you very much for explaining. I think I got it, but I'd like to make sure I see it the right way. I will describe two options which I am choosing from. Please confirm I got the idea right or correct where I am wrong. :)

Option one. Both Cloud and Server have 1 version.

One private space with Variants and Versions is used for preparing documentation updates
Every time documentation changes, we create a new version in this private space
Then we publish a new version to an existing public space, which uses Viewport

Option 2. Server version has multiple version.

One private space with Variants and Versions is used for preparing documentation updates
Every time documentation changes, we create a new version in this private space
Then we publish a new version to a new public space, set up a new Viewport for this space
We modify the viewport theme by adding a new viewport - to have it in the version picker of a switcher.

Best wishes,

Katerina Kolina
Business Analyst
email: kko...@stiltsoft.com

Check out StiltSoft add-ons for Atlassian products

Hi Katerina,

To unsubscribe from this group and stop receiving emails from it, send an email to scroll-viewport-dev+unsubscribe...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/scroll-viewport-dev/86ece483-ad3f-4bce-a643-9580d9b16637%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Scroll Viewport Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to scroll-viewport-dev+unsub...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/scroll-viewport-dev/0d3e5a71-ba65-40a0-bccb-04f693fcfa65%40googlegroups.com.

Steffen Burzlaff (K15t Software)

unread,

Apr 24, 2018, 3:27:39 AM4/24/18

to Scroll Viewport Developers

Hi Katerina,

yes, you can do it that way. Where would be the cloud variant on the second option? If it is in the same space, I am afraid there is no way to choose the cloud variant anymore in the normal variant picker dropdown.

You still could achieve the result, if you have a structure like this:

Root page

Server

page A
page B
...

Cloud

page A
page B
...

With this structure, you could build a menu or a variant picker, which get the children of the root page. Or you just search for the page "Cloud" and insert its link to a Button.

The third option would be an alternative to the second option. If you create two spaces, one for "cloud" and the other for "server".

In the server space, you publish all changes in the same space. (so you won't have to create several spaces with several viewports etc.) The cloud space doesn't need Scroll Versions since there is no version available. But with this approach you would lose the switch "cloud - page A" to "server - page A". You would link to the root page of the variant. So in short:

Server Space

Scroll Versions and Scroll Viewport is active
publishing within the same space
links to the cloud space via a simple link

Cloud Space

Scroll Viewport is active
links to the server space via a simple link

I hope this is helping.

Have a nice day.

Best,

Steffen

Hi Katerina,

To unsubscribe from this group and stop receiving emails from it, send an email to scroll-viewport-dev+unsub...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/scroll-viewport-dev/86ece483-ad3f-4bce-a643-9580d9b16637%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

Katerina Kolina

unread,

May 2, 2018, 2:43:31 PM5/2/18

to scroll-vi...@googlegroups.com

Hi Steffen,

I appreciate you spending all that time for helping me. I thought I got it, but I tried the option one and got confused. Here's what I did:

I had one private space (e.g. 'DOKU private') with 2 variants - Cloud and Server.
I had versions enabled in this private space as well.
I created a public space (e.g. 'DOKU public') and made 2 variants there - Cloud and Server.
My idea was to create a new version in 'DOKU private' for each release and publish 'All pages' to 'DOKU public'.

I didn't need versions for Server in 'DOKU public'
I expected the content of variant Cloud of 'DOKU private' to be published to the variant Cloud in 'DOKU public'. The same with the Server variant. But I got all content from both variants of 'DOKU private' published to each variant in 'DOKU public'

I guess it's expected. In this case, I am confused about how to get it to work. Do I need to use one space instead of private+public? and work on documentation for a new release in a new version and publish it to the same space?

I got a bit lost in all the options we discussed :) To sum up, what option would you recommend if we need:

2 variants
only one version per variant (no version picker for Server)
viewport
would be great if we didn't have to modify the viewport theme every time we update documentation

Thank you for your patience on this one! :)

Best wishes,

Katerina Kolina
Business Analyst
email: kko...@stiltsoft.com

Check out StiltSoft add-ons for Atlassian products

Hi Katerina,

To unsubscribe from this group and stop receiving emails from it, send an email to scroll-viewport-dev+unsubscribe...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/scroll-viewport-dev/86ece483-ad3f-4bce-a643-9580d9b16637%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Scroll Viewport Developers" group.

To unsubscribe from this group and stop receiving emails from it, send an email to scroll-viewport-dev+unsubscribe...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/scroll-viewport-dev/0d3e5a71-ba65-40a0-bccb-04f693fcfa65%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Scroll Viewport Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to scroll-viewport-dev+unsub...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/scroll-viewport-dev/3edccff7-0ed4-4da7-a9aa-fd6db5fc5061%40googlegroups.com.

Roman Serazhiev (K15t Software)

unread,

May 8, 2018, 4:53:36 AM5/8/18

to Scroll Viewport Developers

Hi Katerina.

Scroll Versions doesn't publish the variant information, it simply publishes the pages for the selected variant or all variants. We already have a feature request to publish variant information: https://k15t.jira.com/browse/VSN-3459. Sign up for an account in our Jira to watch and vote on the issue.

You can achieve what you want by activating Viewport in the private space and enabling Variants integration in the settings:

Does it work for your use-case to use just one space for authoring and sharing the content?

Cheers,

Roman.

Katerina Kolina

unread,

May 10, 2018, 10:40:36 AM5/10/18

to scroll-vi...@googlegroups.com

Hi Roman,

Thank you for explaining. Yes, it should work to use one space for authoring and sharing.

Do I understand the workflow correctly?:

1. I set up one space with versions for authoring, 2 variants, a viewport

2. For each documentation update I will create a new version. It will not be seen in the viewport until I publish it. Since I don't need a version picker in the viewport, I will have a new version published to the current space when it's ready. After that a new version will be available in the viewport.

Is it correct?

Best wishes,

Katerina Kolina
Business Analyst
email: kko...@stiltsoft.com

Check out StiltSoft add-ons for Atlassian products

--

You received this message because you are subscribed to the Google Groups "Scroll Viewport Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to scroll-viewport-dev+unsub...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/scroll-viewport-dev/24aea4b2-7f75-4f4e-902a-1d0677c0545b%40googlegroups.com.

Roman Serazhiev (K15t Software)

unread,

May 15, 2018, 4:26:10 AM5/15/18

to Scroll Viewport Developers

Hi Katerina.

Is it correct?

Yes, this is correct. After activating variant integration with Viewport, you just need to publish the latest version to the same space so that the content is visible in Viewport.