[DECIDED] Rule for content on SiteVision or GitHub

[richelbilderbeek]

What to put on SitevVision and what on GitHub?

This is a quote from Marcus Lundberg:

Sitevision is our “landing page”. It’s for “nice” looking pages with general information about UPPMAX, which don’t need to be updated very often. The news function and a calendar of events can be here as well, because it makes sense for this to be visible on our homepage. There’s supposed to be an automatically-generated list of staff as well. MkDocs is for more detailed documentation for our users, for pages that we want to automate, etc. Guides, documentation, anything with code snippets. I’m sure there are things that fall in a grey zone, but we can discuss that a little and then decide what’s best. There is one advantage of Sitevision (besides it being the tool we’re “supposed” to use), which is an automatic accessibility check. I would guess that this is probably available for Mkdocs as well, but I don’t know. Also, Sitevision does have basic version control. Spellcheck can be done by your browser (I assume, as it’s a standard feature with text input on the web).

Or from Björn Claremar:

getting info of which projects to apply for and similar preparations and outside cluster work on www.uu.se/centre/uppmax This is the intention still there are some uncertainty and some exceptions due to history or pragmatic solutions

and

The UU official UPPMAX page is and have to be https://www.uu.se/centrum/uppmax/ (SiteVision) As much info as possible should be there because it is the official page. The docs pages is a solution to solve the needs we think is required for tutorials, code snippets and so on... Some could call it "illegal" perhaps

My suggestion rules would follow from these goals:

SiteVision: the goal is to help people decide if and when to use us, hence is for pages that have potential future users and non-users as a target audience MkDocs: the goal is to help users (i.e. either help themselves and us helping them), hence for pages that have new and current UPPMAX users as a target audience

Then the rule would be:

• SiteVision:
  • Everything our non-users care about, so they can become users
  • Everything that needs to be read by computers, e.g. courses
• MkDocs: Everything our users care about, need to read, want to suggest improvements for

Discussion cases would be:

• Log in to each cluster, now at SiteVision and MkDocs
• Hardware, now at SiteVision and MkDocs
• System usage SiteVision
• Applying for a project
• Courses

[richelbilderbeek]

This is still ongoing ...

[richelbilderbeek]

Here are the notes:

General rule

• Suggestion for overall rule 1

  • Most info on SiteVision

  • All HowTos on MkDocs, example:

    • SiteVision: overview of what we can offer
      • links to project information
    • MkDocs: applying for NIASS projects in

  • YES: BC, RB, ML

  • No: PL

  • PL: I would prefer something like this, clearly defined what category of pages go where. But think many howtos about especially apply for project should be on SV.

What is the guiding premise:

• Until applying on SiteVision (proj application on MkDocs) - All instructions:
  • [VOTED] BC, DI, ML, RB
• Until using (including applying) on SiteVision:
  • ?PL

Applying for an account:

• On SiteVision: ?PL
• On MkDocs: BC, DI, ML, RB

Applying for NAISS projects:

• On SiteVision: ?PL
• On MkDocs: BC, DI, ML, RB

Applying for a local project:

• On SiteVision: ?PL
• On MkDocs: BC, DI, ML, RB

PUBA:

• On SiteVision:
• On MkDocs: BC, DI, ML, RB, ?PL

Hardware:

• On SiteVision:
• On MkDocs:

Instructions about (howto) Services offered through UIT (if a page is needed):

• On SiteVision:
• On MkDocs: RB, DI, ML

• Suggestion for overall rule 2

  • [VOTED]: try hard for minimal duplication
  • Minimize double info
    • [VOTED] Yes: BC, RB, PL
    • No
  • 2b: absolutely no double (no pragmatism)
    • Yes: PL
    • No: BC, RB, PL
  • PL: I vote for both... "no pragmatism" sounds a bit harsh, but we should really minimize hard. The end user experience gets confusing when info are in two places - "am I reading in the correct place?" One page would be best. If we need two pages it is good if they are clearly defined to cover different parts, this will also minimize the times you have to jump between the two pages.

• Suggestion for other alternative rule(s)

  • Extreme MkDocs:
    • everything except links to mkdocs on SiteVision
    • no subpages
  • Almost Extreme MkDocs:
    • keep subpages but only put links here
  • Like today
    • on cluster on MkDocs
    • Project management on SiteVision
  • More SiteVision: PL
    • Some MkDocs content --> SiteVision
    • As much as possible on SiteVision
    • Only use mkdocs when we can motivate it
      • dynamic pages (sw list)
      • frequently updates pages - easier on mkdocs(?)
      • lots of code - easier with markdown

Specific topics

• Log in to each cluster, now at SiteVision And MkDocs

  • SiteVision only:
    • Cons/pros??
  • MkDocs only: BC, RB, PL (if other howtos/userguides are on mkdocs)
  • Both

• General description of hardware, now at SiteVision and MkDocs

  • [VOTED] SiteVision only: DI, ML, BC
  • MkDocs only: RB
  • Both:

• Detailed Hardware (how to access), now at SiteVision and MkDocs

  • SiteVision only:
  • [VOTED] MkDocs only: DI, BC, RB, ML https://github.com/UPPMAX/UPPMAX-documentation/blob/main/docs/hardware/clusters/rackham.md

• System usage, now a link from SiteVision to mkdocs

  • Link from SiteVision
  • Link from MkDocs (move):
  • [VOTED] Link from Both: RB, BC, ML, DI
  • PL: this might become problematic on SV in the future if we want to add more, and more dynamic content. job dashbords and such. But we can move to mkdocs later if necessary.

• Applying for a projects and accounts, now SiteVision

  • Problem today: can be much more pedagocigal in MkDocs
    • PL: "can be much more pedagogical" - how?
  • SiteVision (keep): PL
  • MkDocs (move): RB
  • Both: BC
    • Example:
      • Info about projects in SiteVision
      • How to: in MkDocs, of course with links from SiteVision

• Our Courses, Now SiteVision

  • https://www.uu.se/en/centre/uppmax/study/courses-and-workshops
  • SiteVision (keep): BC, PL
    • Pro: we can keep the existing formatting
  • MkDocs (move):
    • Pro: Everyone can easily modify their courses. Don't have to bother about swedish + english versions that have to be in phase
      • Example: Singularity was just updated in Eng version
      • However: important to make the existence of courses visible on SV
  • Both: listing courses on SV, course pages on MkDocs
    • [VOTED] BC, RB, DI, ML,

Course registrations:

• Use SiteVision form for future course registrations:
  • Yes: ML, DI
  • No:
  • Neutral: RB
  • [VOTED] Investigate first, then move to future meeting

SiteVision additions:

• SV calender/news (courses instance?)

  • Move to later meeting

• Support on SiteVision (consists of links), now duplicated

  • [VOTED] Keep: PL, BC, ML, DI (and keep what we have on MkDocs)
  • Mkdocs (move): RB

• Links back?

  • Can links in the mkdocs menu redirect to SiteVision?
  • For example, the Support link at the top could go to support in sitevision
  • Keep things as they are!

[richelbilderbeek]

I will put this at CONTRIBUTING.md :-)

[richelbilderbeek]

It has been put in CONTRIBUTING.md . Done!