Take care on doc pages permalink

[dragotin]

As discussed:

We need to find a method how to reference html doc content in products in such a way where the link used in the product does not need any change when the html target link changes.

@mmattel please propose a schema that can be implemented in web and create the issue there once done. Thanks!

[mmattel]

First of all we need to clarify how redirecting with Antora works for a common understanding and finding the right solution.

Antora is not a webserver but a static site builder. You can only redirect to pages:

1. The existing page is part of the content catalog (explanation see later)
2. The existing page got moved from one location to another
3. You want to have access to that moved page but via the former location
4. A direct call to the relocated page including an anchor (my-page.html#section) works
5. When issuing a call to the redirection page containing an anchor to a section, the anchor gets cut off by design of the HTML redirection page. This means you get redirected to the page on the new location but not the section (anchor) in that page.

How this works: You add a redirect rule in the moved page telling where it was (page-aliases). When building, this creates an invisible html page per alias on the former location which redirects to the new location. You can set more than one alias for one page. The sitemap file(s) are populated correctly based on the content catalog but do not contain the redirection page(s).

This is (shortened a lot) the main part how the redirection is created, standard HTML, no influence: <meta http-equiv="refresh" content="time; URL=new_url" />

You can use this mechanism for moved but not for deleted pages as a target is missing. Except when pointing to a "best fit" existing page.

Lets call that reverse redirect because the page already existed.

Solution scenarios:

What we need here is the opposite. We need a forward redirection. We do not care if the page existed or not, we either need to rewrite the URL right from the beginning or use a target HTML page that redirects to the final location.

There are only two choices doing this. Antora or the webserver.

• When using the webserver, we do URL rewrite and anchors are kept as only the url is replaced. /whereever/whatever.html#look-at-it --> /new-location/new-file.html#look-at-it
• When using Antora, the final page to be shown gets a page-aliases with a "dummy" path/filename. This dummy path/filename.html is accessed by the webUI code (not the final target!) and always points therefore to the correct page, but you will lose the anchor in the source request. /path/filename.html#look-at-it --> /new-location/new-file.html Note that path/filename does not show up anywhere except the target page. One needs to know it...

There are pros and cons for both methods but as far I can tell, keeping the anchor is essential until stated differently.

• We had implemented for ownCloud Server a php based webserver mechanism that works well and can be "reused". This of course splits tasks a bit as in such a case any change needs involving admins. Rare but happens. Possibilities to maintain the php script from the docs team can be considered but needs clarification.
• If it is ok that we can redirect to a page but not to the section in the page because the anchor is dropped, we can do this with the docs team / Antora alone.

Please advise.

@dragotin @JanAckermann @xoxys

[AlexAndBear]

I don't want to interfere here too much but:

If it is ok that we can redirect to a page but not to the section in the page because the anchor is dropped, we can do this with the docs team / Antora alone.

I don't see this as a good solution, we really want to take the user by the hand and help them to find the corresponding doc record

I can't say anything about the technical solution, but a regular web server like nginx or apache should be able to rewrite the urls, but its not super handy for the doc team, because it might require the help of an admin each time adding a new alias

[michaelstingl]

I'd vote for the page-aliases. I'm aware that anchors don't work, but permalinked content is too important to be hidden behind an anchor. It should always an individual page. Big benefit of page-aliases I see, it's transparent for all contributors. I could take care of changes in desktop and mobile apps to support page-aliases links. Just let me know…

[dragotin]

Ok, please implement this using page-aliases as described, unless @kulmann vetos.

[kulmann]

Ok, please implement this using page-aliases as described, unless @kulmann vetos.

fine by me, please go ahead

[mmattel]

@kulmann @JanAckermann

We currently have, relevant for ocis/owncloud-web:

• ownCloud Web for Users
• ownCloud Web for Admins

1. These main links can immediately be referenced by the webui team.
2. If there is any structural change, which I doubt it will take place in the next year(s), I will create a internal link that references to the new target. Means no change for the webui team.
3. Note that though you can atm reference to a section, I please you NOT to do so as this is more likely a subject of change.
4. I will add a comment in the two pages to remind that these documents are linked by the webui and need to be resolvable under the above html links.

[AlexAndBear]

What are the plans for the future ? Currently we just link to the sharing section. Replacing that link to the general docs for web users w/o section, feels like a step backwards instead of forward

[kulmann]

Fully agree with @JanAckermann , only being able to link to the main pages for Users or Admins is a step backwards. That's also not at all what I understood from all the posts above. Could you please explain your plans here @mmattel

[mmattel]

Could you please explain your plans

As described above, there are only two ways:

• Page only redirect via Antora (HTML)
  • occurs on the first document change that either renames/moves the page or section
  • fully maintainable by the doc team
  • no sysamin intervention necessary
• Page+anchor redirect via the webserver
  • must be done right from the beginning
  • using the go.php implementation we already have needs to be extended to the webui (is then automatically available to other products too) (not a big deal, in a nutshell it matches a string to be used as source to a target)
  • maintenance can be done by the doc team, need access to the source script
  • sysadmin support necessary in the implementation phase and when the doc team is stuck

Pros and cons for both version, I follow the decision that is/will be made.

[kulmann]

I read what you described above. And there was a decision for Page only redirect via Antora managed by docs team. But after that decision was made you told us to only link to the root page of the User and Admin docs. Which is not a good solution. I don't understand why we shouldn't link to the specific sub pages.

[mmattel]

why we shouldn't link to the specific sub pages.

Lets split this into three cases

• As written above, it works for now, but any change on the page name/location, I have to write a so called page-alias which creates a html file redirecting to the new page but strips off any sections by design of the html redirect. Nothing I can do about.
• It is possible to make anchors stay the same even the underlaying section printout is different, but this is by experience a nightmare to maintain when you have to restructure sections and text - and this will definitely happen over time. Accessing an anchor that does not exists points to the top of the page like if you not have used the anchor at all.

Add on note:

• What also can very likely happen is, that we have to split up pages into two or more to keep readbility. I am worrying about this one most. In such a case the anchor can be handled like described above but not the page address (where to redirect?).

[kulmann]

Easy consequence: If we can't link to specific pages of the documentation then I will remove all links to the documentation from the web ui contextual helpers.

[mmattel]

You always can point to https://doc.owncloud.com/webui/next/

[xoxys]

I'm confused... What's the problem while linking to sub-pages? This should work without any issue, the only restriction is that linking to anchors will not work. If linking to anchors is a hard requirement, make the proper decision that a setup that supports anchors is needed, and we need to plan a setup.

[kulmann]

I'm confused... What's the problem while linking to sub-pages? This should work without any issue, the only restriction is that linking to anchors will not work. If linking to anchors is a hard requirement, make the proper decision that a setup that supports anchors is needed, and we need to plan a setup.

Yeah me as well!

• Not using anchors is a compromise I am willing to accept.
• Not being allowed to link to a sub page is not a compromise I am willing to accept. I thought the whole point of the page aliases was that you don't discontinue existing links out there (which is not only relevant for oC Web but also for search engines, blogs, ...)

[mmattel]

I would really like to have the stakeholders in a call so they can express their need, we can explain the possibilities with their pros and cons and find a decision that all stakeholders can and will live with.

[AlexAndBear]

@xoxys we don't care much about how the link looks like, anchor or not. We just need a link which is directing us to the sharing section for example (that's the onliest link to docs in web for now).

Is this possible or not, ticket is open for 21d now and I don't see things proceeding. Just back and forth communication.

[kulmann]

I would really like to have the stakeholders in a call so they can express their need, we can explain the possibilities with their pros and cons and find a decision that all stakeholders can and will live with.

Again, the decision is already there. Use alias links page aliases so that you can provide stable links to documentation pages. But right after the decision was made you told everyone in this ticket that a) page aliases to any page of the documentation are possible but b) you don't want to make use of them and everyone should only link to the root page of the docs.

Edit: On top of that, the requirement from the CTO of the company is clearly written down in the initial issue description and was confirmed by product owners. I don't see a need for a meeting.

[xoxys]

I dont get your points... You dont care about the details and arguments like "decision was made already" if this decision does not fit your needs is somehow strange...

Technical details matters because they are relevant in case of the chosen solution.. However if you want our team to set up something let us know otherwise im out for now.

[AlexAndBear]

@xoxys yes, please set up something that matches our needs, like I described above.

[xoxys]

Ok will create an internal ticket. As we are working ok other priority tasks this will take some time.

[AlexAndBear]

Thanks for taking care 🙏🙏🙏

[xoxys]

I need a list of all links you want to use in web. We will then provide you a permalink for each of them to use. Remember, using this method requires that you will notify us every time you want to use a new URL in web, so we can prepare a new permalink first.

[AlexAndBear]

sure that's the list:

• https://doc.owncloud.com/webui/next/owncloud_web/web_for_users.html#sharing

(Yep, just 1)

[mmattel]

@xoxys mind to share how you think that could be implemented on the webserver side? I guess to know such a mechanism could be beneficial for other codebases too... just my 2c.

[xoxys]

Sure it will be just the same we use for core.

[mmattel]

May I do a proposal with regards to the naming of the used link: I core we have as example: href="https://doc.owncloud.com/server/go.php?to=admin-performance"

To make this more futureproof, I suggest:

• we only use the main URL to docs
• for the to= string that this starts with the product:

Examples: href="https://doc.owncloud.com/go.php?to=webui-sharing" href="https://doc.owncloud.com/go.php?to=desktop-vfs" href="https://doc.owncloud.com/go.php?to=anfroid-spaces" href="https://doc.owncloud.com/go.php?to=ios-spaces"

Having that, we can easily identify where this belongs to and would be open to any future changes.

[xoxys]

I dont have any personal preference, if that helps you we can name it that way, but I'll cut off the useless pseudo-php extension this time. Means links will be https://doc.owncloud.com/go?to=webui-sharing

[dragotin]

A new aspect (for me at least) is that we have to allow anchors in the links, because currently the docs are structured in the way that there are only a few separate pages, structured with anchors. If we are not allowing anchors, the whole feature is pointless, because we can not link to specific topics.

I suggest the following:

• The documentation becomes versioned by major version numbers (ocis 2, ocis 3, ocis 4)
• Within a release, the doc links have to remain stable
• The clients use the hardcoded links with anchors
• Structure changes in the docs can be done between releases, and clients have to be informed by the doc team of relevant changes
• There should be a CI script that checks if all link targets exist

I realize that this is a compromise, but well...

[mmattel]

Plan to versionize the Infinite Scale documentation (user and admin):

General info, the current way of versioning the ocsi admin docs is made via text notes and tabs containing content relevant for a version.

OCIS (admin docs)

• Create a new 2.0 branch to reflect the the current state (next and 2.0)
• Separate version content that is currently reflected by tabs into the respective branch
  • Untangle the automated content setup which is done by variables and partials
  • Needs to by done by each branch individually, backporting not possible Note that some text content has already been changed like "Starting with ocis 3.0, ...". This content can not be reversed to 2.0 content.
• Fix the doc generation process with respect branches
  • As we have dependencies with other doc repos, this needs to be checked and fixed by each referencing or referenced repo individually
• Any change needs careful sub-planning to guarantee continuous web content accessability
• Testing

ownCloud Web (user docs)

• Versioning the ocis user documentation has a major impact as we decided when setup that both ownCloud server and the ocis user docs will reside in the same repo and therefore in the same URL namespace (webui). This decision was based on that major changes in the webui url degrade over time quickly close to zero.
• With the current setup, when adding versioning to the webui component, both server and the ocis ui get versioned which does not fit to the server part. This leads to the following:
  • Creating individual components (new URL) for user docs for server and ocis.
    • Page Aliasing all server documents to the new address
    • As we have dependencies with other doc repos, this needs to be checked and fixed by each referencing or referenced repo individually
    • Fix the doc generation process
• Any change needs careful sub-planning to guarantee continuous web content accessability
• Testing

Effort

• For each part, expect that at minimum one man week is needed.
• During the transition phase:
  • NO additional tasks can be processed like monitoring and correcting things in the ocis repo with impact to docs
  • No issues can be created or processed in any docs repo
  • NO PR's can be filed like fixes or new content in any docs repo

Pls let me know when I should start.

[gedw99]

What about using a CID ? Content Identifier.

Same as what IPFS uses for this exact problem of Providence of where content came from and hence where it is over time. The old Time / space problem :)

---

How to do the same concept in OCIS ?

OCIS NATS server can notify a Consumer of when a document changes and its URI could / should be one of the things it notifies of. Its part of security audit trailing anyway. hence why i referred to Providence.

SO then any Actor can then track a documents URI over time by consuming off NATS Notifications.

https://owncloud.dev/services/notifications/ looks like its already used for tracking things that are related to this area.

https://owncloud.dev/services/storage-publiclink/ seems that it might be something related. no doc yet though so hard to know.

[tbsbdr]

docmeeting: @micbar please decide how to proceed

[mmattel]

@micbar as discussed in the Doc Board Meeting and as requested, I would like to propose an alternative approach which imho leads to the desired result in permalinks on a global docs scope with minimal efforts. Not only for the webui but for all doc modules and also for any produc that uses/will use links#anchors to docs. Note that whomever I asked about how they would approach this, the same answer was given.

Also Note that we have a well working example for this proposal - core.

• In a nutshell, use the webserver as mediator as only he accesses all the content correctly and can do redirects in a proper way including anchors. To achieve this and to relax sysadmin efforts, there is a one time taks on the sysadmin side to implement a docs wide valid go.php (or however we name it) mediator that loads a docs maintained translation list from a source string to a target link.
• This makes any links#anchors changes that can come in docs totally independent of what a client has coded.
• There is no maintenance on the sysadmin side necessary and a on occurence maintenance task on the docs side if a target changes because of what reason ever.
• The thougt that any major/minor doc changes or redefining anchors will go away with splitting docs just for permalinks is just not true and will cause more work, overhead and directing readers from the clients not to the desired content.

Please take this into your considerations.

[micbar]

@xoxys I need an effort estimation. Sorry that this ticket has exploded so much.

If i understand the proposal correctly,

1) Webserver setup is a one time effort 2) The redirect list will be maintained by the docs team

[xoxys]

@micbar please decide how to proceed

I don't know what decision was made, so I can't estimate.

In a nutshell, use the webserver as mediator as only he accesses all the content correctly and can do redirects in a proper way including anchors. To achieve this and to relax sysadmin efforts, there is a one time taks on the sysadmin side to implement a docs wide valid go.php (or however we name it) mediator that loads a docs maintained translation list from a source string to a target link.

This will never happen for security reasons. We will not allow sideloading any web server configuration.

[micbar]

This issue is a total mess 😅

There was a decision made by @dragotin But @mmattel says it is not actionable.

I am just trying to reduce that mess and understand the consequences.

If i understand you correctly, loading a list of redirects from a not sysadmin managed system is a total No-Go.

Under the assumption that my assumption is correct, i assume now @mmattel that your proposal is not working.

This brings me to the assumption that the original idea (use page aliases) may be the right way to go. Ironically this was already decided 🤣

So what should I do now? I am tempted to open up an arena to make new proposals, buy some 🍿 and watch.

Please do not take this personally, I am trying to find a solution ❤️

[xoxys]

I don't know why 73 new proposals were made again. We need a persistent way to link to some parts of the docs, and these permalinks need to support anchors. End of the story.

To get this working, we will prepare permalinks on the web server. Whenever the docs team decides to change the target of this permalink in a way that can't be fixed by page aliases, they need to create an Issue or PR in the internal deployment repo to get it fixed (or avoid refactoring the basic structure frequently). But honestly, if you need to change this redirect config every week, then this approach is the wrong way. Personally, I also don't see why the page structure need to be changed that often.

As there is currently only a single link (at least only this one was reported) the estimated time to set it up is 15 minutes but till low priority on my list. If we are now finally done discussing this over and over again, I can implement it by the end of the week. But it looks like you and me were not invited to the docs meeting, so I have no idea what's the real problem is... If you need some time to find out, just ping me again later.

[AlexAndBear]

As there is currently only a single link (at least only this one was reported)

Just here to confirm, this is still the case...

[mmattel]

if you need to change this redirect config every week, then this approach is the wrong way. Personally, I also don't see why the page structure need to be changed that often.

I am not expecting this occuring more than once a year, usually in longer intervals. From experience on ownCloud server we know that this is extremely static. The last time I can remember this was ~20m ago.

[xoxys]

sure that's the list:

* https://doc.owncloud.com/webui/next/owncloud_web/web_for_users.html#sharing

Done: https://doc.owncloud.com/go?to=webui-users-sharing

[AlexAndBear]

Done here as well: https://github.com/owncloud/web/pull/9567

that was a wild ride, closing