Add docs with general info about Tobira

[LukasKalbertodt]

I wrote this a few months ago and never got around to creating a PR.

I'm unsure about this in two ways:

• I'm not sure if I have explained these things sufficiently good. Maybe my explanation is confusing, too technical, or maybe even too long?

• I'm not sure if this kind of information should be in our docs. My intention for it was that we have well defined terms for our future discussions.

What do you think? Als interested in the opinion of @oas777 and @dagraf. As this is just a documentation pull request, you can click the "files changed" tab to see what documentation I suggest adding.

[dagraf]

@LukasKalbertodt: Here some suggestions on how to formulate the general informations. In a word file with track change, since I am not that familiar with github-files. I hope that works for you. Let me know, what you think.

User Manual for Github_20230920.docx

[oas777]

Given there's a lot of edits already, I'm not going to use David's DOCX. Instead, a couple of comments:

• I think we should differentiate "Pages" as described from "video pages" (e. g. https://tobira.opencast.org/lectures/d-infk/2019/autumn/263-3010-00L/v/IQ_MQQIbg2U): These have no sub-pages, no content blocks, and a different appearance alltogether.
• Should we mention/define the "user part" of Tobira which sits under https://tobira.opencast.org/~manage (in-/excluding Studio)?
• Definition of user pages should include their URL https://tobira.opencast.org/@USERNAME
• Define/name these elements (for reference, DE/EN)?
  
  
  
  
  

[LukasKalbertodt]

As a meta comment: I think we are not really clear about the target audience of this document. Is it people involved in development to communicate precisely? Is it a specification of how Tobira behaves? Is it a manual for users? ...? We should probably decide that before discussing anything else.

The rest of my comment will now discuss something else.

---

I pushed a new version. This incooperates most of David's suggestions, with exception of the last part ("unlisted" and stuff). I wanted to wait with this until we reach consensus on all other things. Some remarks to your suggestions:

page tree, which is shown on the very left side

Well, technically, only part of the page tree is shown on the left side. And the navigation can show other stuff, depending on the site you are on.

(Explanation of blocks)

I'm not sure if it's really worth explaining those in more detail here. Your descriptions for text and series blocks are also pretty... hollow, not adding any information.

---

• I think we should differentiate "Pages" as described from "video pages" (e. g. https://tobira.opencast.org/lectures/d-infk/2019/autumn/263-3010-00L/v/IQ_MQQIbg2U): These have no sub-pages, no content blocks, and a different appearance alltogether.
  What exactly do you mean by that? Should we not use the word "page" in the term "video page"?

But yeah, I think it's a pretty tricky situation. "Pages" is such a general term. So using that word for the editable "pages" (as described) specifically, is problematic. In our code, we use "realm" as you might know, to avoid that ambiguity. But we didn't think that was an appropriate term to use in the UI. It might be a bit late to change "page" as term for these things, but if you have any good suggestions... please!

• Should we mention/define the "user part" of Tobira which sits under https://tobira.opencast.org/~manage (in-/excluding Studio)?

Mhhh, we often called it "management area", right?

• Definition of user pages should include their URL https://tobira.opencast.org/@USERNAME

I don't understand: the user page section includes a couple of example URLs. Well, it includes the paths, without the tobira.opencast.org domain part. But that's explained in the document. Repeating the domain part in every example felt unnecessary to me. Or would you disagree and include it? I can see why one would want to do that.

• Define/name these elements (for reference, DE/EN)?

That's a good idea! Will do.

[dagraf]

Some thoughts to your last commit and comment:

• Target audience of this document: People involved in development and people involved in running/supporting Tobira at their own institution.
• Thanks for the new version. I can live with all the changes you made, but: I would still be in favor of using the term "Videos in context". I think, this is the same as Olafs' "Video pages".
• If we should mention the "management area", I would keep it as short as possible. Because of the target audience.

[LukasKalbertodt]

I added 3 commits. Most interestingly:

• There is a big image now labeling important UI elements, as suggested by Olaf.
• I use the term "content page" now to avoid the problem of confusion with the generic "page" term.

Thanks for the new version. I can live with all the changes you made, but: I would still be in favor of using the term "Videos in context".

I think I simply missed that in your suggestions. I did not omit it on purpose. Fixed now.

[LukasKalbertodt]

For ease of reviewing:

Semantics and definitions _ Tobira documentation.pdf

[oas777]

Finally... this looks good in general. But I have to come back to one of my original comments:

• I think we should differentiate "Pages" as described from "video pages" (e. g. https://tobira.opencast.org/lectures/d-infk/2019/autumn/263-3010-00L/v/IQ_MQQIbg2U): These have no sub-pages, no content blocks, and a different appearance alltogether.

These are now "Videos in context" and they appear under "Routes", correct? Which I don't think is adequate. I think they deserve a chapter of their own (after "Content Pages") and a better name. Mainly because they will be like 95% of the pages in a custom video portal. Or am I missing something (looking at the PDF mainly)?

[LukasKalbertodt]

I just added a short video page chapter. I hope this should clarify things. Let me know what you think Olaf.

Here you can see what exactly I changed, and here is the rendered PDF version:
Semantics and definitions _ Tobira documentation.pdf

[oas777]

All good, thanks - even if that "short ... page" still underrepresents the quantity of video pages! Two comments:

• "(Content that also appears on public pages, will also appear in the search.) From the paragraph on content pages. Maybe "Content and/or videos from user pages re-used in the main-page tree will appear as search result if public." Weird parentheses BTW.
• The main place to watch a video is the video page. It contains the video player ...

[LukasKalbertodt]

Good points.

"(Content that also appears on public pages, will also appear in the search.) From the paragraph on content pages. Maybe "Content and/or videos from user pages re-used in the main-page tree will appear as search result if public." Weird parentheses BTW.

I removed that sentence completely and by simply changing the previous sentence. I think it is clearer now.

---

Latest changes and the rendered new version: Semantics and definitions _ Tobira documentation2.pdf.

[LukasKalbertodt]

I forgot to mention this yesterday. @oas777 @dagraf can this be merged? Would be nice to finally get this over with. Adjustments can still be done later of course.

[oas777]

+1 for merging

[LukasKalbertodt]

Then lets just do it!