New documentation

Yep, scheduled for next redeployment. Thanks!

EDIT: Redeployed, should be fixed now.

1 Like

Very brief comments (only had time to skim over it):

  • please state some policy regarding the maintenance mode of the docs
  • all sections should state a date of last update, the OS version they refer to, or, in best case, both (especially those which shall not be actively maintained in the future)
  • for better readability, it would be great if the individual HW-specific section could be collapsed/expanded by the reader (I would actually prefer collapsed by default, but YMMV)

Good start, thanks a lot, keep it up if possible!

It should be actively maintained and it should therefor contain only stuff we actively maintain. Unless stated otherwise, it reflects the latest version of Turris OS. There is only few pages that depend on HW - mostly HW section, so for now we kept it simple. Last modification date sounds like a good idea, will look into that. Would prefer to avoid TurrisOS version to avoid mass version bumps on every release.

One note regarding the second part of the docs (for simplicity, I would now call it “community docs”).

As I understand it (please correct me if I’m wrong), the team considers it out-of-scope from now on, leaving it basically unmaintained. Since someone had to go through all the docs quite recently (to decide which part should which documentation page belong to), it could be feasible to tag even in the community docs:

  • if it is obsolete
  • which version of SW or which HW it is applicable to

Of course, I mean this as a one-time tagging only, in order to have a reference point for the future.

Last, please consider within the new interface:

  • to add a possibility of switching languages, or to filter for language versions shown
  • to have a page with the whole documentation tree (aka ‘Table of Contents’) in one page (especially when searching for solution of a problem, not knowing whether there is documentation for it at all)

The plan is for community wiki to stay alive and function in similar manner that the community sections worked till now. Let people document interesting setups that are out of our scope. The plan is to drop the “official part” after some adjustment period and after moving all articles written there somewhere.

Currently there is only English version, over the time we might add separate language mutations if requested, but work on that haven’t even started yet. Regarding documentation tree, search seems to work better and we put everything that should be accessible into navigation on the left, but everything is collapsed by default for obvious reasons.

I think there is one thing that could be enhanced:
Explanation/documentation of turris development branches inside https://doc.turris.cz/doc/en/howto/release_candidate. Calling https://repo.turris.cz/, one can find following up-to-date branches:

  • ☞🐈
  • ☞🐉
  • ☞🐌
  • ☞🐢
  • hbd
  • hbdb
  • hbd-4.0
  • hbk
  • hbs
  • hbt
  • master (which is outdated for MOX btw)

In documentation one can find

  • Deploy
  • RC
  • Daily
  • Nightly
  • Test

I would assume the following:

  1. hbd is Deploy
    a. hbd-4.0 is deploy-branch for Turris OS 4.0
  2. hbs is RC
  3. hbdb is Daily
  4. hbk is Nightly
  5. hbt is Test
    a. master is testing branch of actual OpenWRT “https://downloads.openwrt.org/snapshots/targets/” releases

Where the emoticon-branches come in I can not imagine.
Can you please comment on my interpretation? Thanks :slight_smile:
edit: Question arose because I am about to update my Omnias with medkit and didn’t know which branch to take for it.

I couldn’t find the post where it was explained but i think it should at the moment be something like this

  • hbd - Here Be Dragons - TOS5
  • hbk - Here Be Kittens -TOS5
  • hbt - Here Be Test (Turtle) - TOS4
  • hbs - Here Be Stable (Snail) - TOS4
  • hbd-4.0 - Here Be Dragons - TOS4
  • master - TOS3
  • hbdb ? maybe Here Be Daily Branch

Dragons are very early unstable versions (alpha), Kittens are like beta versions.
Turtles move faster than Snails, so they should be RC and Deploy respectively.
It would be nice if there where an easy to find explanation right there at the root of the repository.

1 Like

We tried to explain it in this article in our new documentation: https://docs.turris.cz/geek/testing/
As we released Turris OS 4.0 during the weekend, we will redirect some pages from our old official documentation site.

3 Likes

Lions are coming.

2 Likes

We have introduced some redirects to navigate new users correctly.

Original URLs on doc.turris.cz are still valid (such as doc.turris.cz/doc/en/start), however the root of the original “doc” (doc.turris.cz/) is redirected to new “docs”.

Already mentioned wiki URL is untouched, so you can access the original documentation easily with wiki.turris.cz.

Other redirects will follow…

2 Likes

Is there a way to contribute to the new documentation? For the old one you can create an account. I did it and I changed a little something. The new one has sections that would need major tweaks. Like this section https://docs.turris.cz/hw/omnia/serial-boot/
If it weren’t for the Debian guide https://wiki.debian.org/InstallingDebianOn/TurrisOmnia#Installation I never would have understood how to flash U-boot. While there was no hope to flash the recovery image. The guide as it is written is misleading and does not allow in any way to achieve the result. To realize this, just compare the Bootloader update part of the Debian guide and that of the Omnia guide.

You can fork the project at GitHub (https://github.com/CZ-NIC/turris-user-docs) and create a pull request (like these ones: https://github.com/CZ-NIC/turris-user-docs/pulls).

Ok, thank you so much.

1 Like

Is this still the way to go? Nowadays, Github is only mirroring the GitLab project.
On your GitLab instance, do you work with forks or do you accept merge requests on the main project?

Due to some security measures determined by our administrators, project forks on our GitLab instance are disabled by default. They can be enabled for external users only in exceptional cases. There are multiple ways how to contribute - please read the related documentation page.