Page MenuHomeSoftware Heritage

sysadm docs: Move relevant and public doc from intranet to swh-docs
Closed, ResolvedPublic

Description

After discussion the following structure emerged as proposal for the sysadm pages. After
the sprint, the arborescence evolved a bit but the gist of it remains. We want to
migrate the existing intranet pages to the sphinx instance.

A new page [1] to add the documentation site. This could be publicly linked from the
main page [2] (or not). This will be publicly exposed as other repositories already
exposed the same kind of information anyway (source code repositories, puppet, ...).

[1] https://docs.softwareheritage.org/sysadm/

[2] https://docs.softwareheritage.org/

Pros/cons

pros

  • code review ahead of time available (one could always skip it if they don't want to)
  • tool unification (sphinx rst, git, ...)

cons

No cons that I can see (well the migration per say but that can be done incrementally :)

Remaining pages to redispatch eventually

Event Timeline

ardumont triaged this task as Normal priority.Mar 18 2021, 11:57 AM
ardumont created this task.
ardumont updated the task description. (Show Details)

The sysadm team is ok on this [1]

And like i mention in the crash ticket [2], moving to this scheme brings another pros to the
party, making the docs access more resilient.

[1]

12:34 <+olasd> in any case, I think I've voiced my concerns already. I don't like the idea of moving away from the wiki(s) to something with a much higher barrier to contribution (sphinx + restructured text + code review + git), but the unification and restructuring of docs probably outweighs this concern
12:35 <+olasd> and in that sense I'me fine with the proposal
12:36 <+olasd> (and the thing I'd want us to move towards doesn't exist yet, so...)

(quoting here because as usual, the arguments were nicely put and worth mentioning)

[2] T3444

@olasd , @ardumont and @vsellier : I think that we can gently resolve this task.

Thank you for a very fruitful sprint[1]!

[1] https://hedgedoc.softwareheritage.org/2021-october-documentation-sprint?edit

ardumont renamed this task from proposal: sysadm docs: Move relevant and public doc from intranet to swh-docs to sysadm docs: Move relevant and public doc from intranet to swh-docs.Oct 14 2021, 1:15 PM
ardumont changed the task status from Open to Work in Progress.Oct 14 2021, 3:00 PM
ardumont moved this task from Backlog to in-progress on the System administration board.

We have followed the plan on the hedgedoc (in the last comment).
Just realized we haven't decided if the support-tools should be in sys-admin dimension, so I'm adding this to this task to decide.

section: Support services

Makes sense to me to add them in sysadm.
Also, jsyk, currently, the support-services stub files are already present in the sysadm instance, remains to to fill in the blank at some point.

2 more pages migrated (published and redirect installed in the intranet):

(which i used to outboard hakb \o/, i believe that's the first time I actually outboard someone, i usually do the onboarding ;)

ardumont updated the task description. (Show Details)
ardumont updated the task description. (Show Details)
ardumont updated the task description. (Show Details)
ardumont updated the task description. (Show Details)
ardumont updated the task description. (Show Details)

All existing sysadm pages have been migration from the wiki and from the intranet to the docs.softwareheritage.org/sysadm pages.
The redirection have also been configured to those pages.

So this can be closed now.

ardumont moved this task from deployed/landed to done on the System administration board.