Skip to content

Latest commit

 

History

History
135 lines (117 loc) · 7.5 KB

STYLEGUIDE.md

File metadata and controls

135 lines (117 loc) · 7.5 KB

Content and formatting instructions

General help

  • Markdown syntax guide
  • Also some special markup possible, e.g. admonitions (colored highlight boxes). Please look at Markdown source for examples, and use preview
  • A reference card is available along with Markdown source for reference card
  • When in doubt, check how other pages are formatted
    • An example of a well-formatted page is the one on disk areas (source file), including examples on how to format code blocks, tables and admonitions
  • Note that pages under a certain category may have a unified formatting that should be followed
    • For example, application pages should have Available (which versions and on which systems), License (free or somehow restricted), Usage (how to load module, example batch scripts), References (what should be cited) and More information (links to e.g official documentation) headers, in that order.

Organizing content

  • Try to make standalone articles with a good name (user knows to select it from the left menu)
  • The content should be as concise as possible, but as lengthy as needed.
  • The main user guide should document only what is specific to CSC environment, for general usage instructions link to the real manuals of the tool
    • Lengthier tutorials can be written under Support->Tutorials.
  • Don't make too deep hierarchy or too many entries per subcategory (combine very small pages)
  • Don't refer to the same page twice in mkdocs.yml -> sitemap breaks + weird menu action
  • If possible, try to keep your markdown lines shorter than 100 columns to improve readability and reviewability of the source material
    • Note that, for example, tables and preformatted code blocks cannot be split, but ordinary paragraphs and bulleted lists will render perfectly fine when there are line breaks in the source material

Accessibility

  • General guidelines
  • Make accessible content! In short:
  • Links:
  • Images:
    • Use descriptive alt-text and mouse-over (title) in images: ![This alt-text is for screen readers](/img/image.png 'Helpful text shown as mouse-over'). Images should be of high contrast and large enough font within them. See FAQ for details.
  • Videos:
    • Use title to describe the video content. See FAQ for details.
    • Present important or difficult to follow things with videos. However, avoid presenting something ONLY as a video. Use captions/subtitles in the video (easy to add in Youtube).
  • Headers:
    • Only one h1 (#) per page
    • Follow heading structure (don't go from h1 to h3 = # to ###). Don't make deep structures (they will confuse the table of contents).
  • Avoid long walls of text and long sentences
  • Lists and clear titles: good
  • Avoid using loadable pdfs
  • Avoid using only color to signal some meaning

Embedded Videos

  • Iframes to youtube need to use the srcdoc attribute instead of src. This is a workaround we use to avoid cookies if consent has not been granted. See FAQ for details.

Links

  • See FAQ for details.
  • For internal links, include .md in the target, for example:
    • [cool page](page.md)
    • [stuff in page](page.md#anchor)
    • [stuff in other section](../other_section/page.md)
    • [stuff elsewhere in page](../other_section/page.md#anchor)
  • Do not make internal links with https://docs.csc.fi/..., the tests will fail!

Tables

Images, linked documents

Syntax highlighting

  • Write SLURM flags in long format (--nodes instead of -N, etc.)
  • All examples should use minimum viable reserved resources. So don't write examples with --t=72:00:00 or --gres=gpu:v100:4 or --cpus-per-task=40, if not needed. Users tend to use these as default values.
  • For code sections (marked with three backticks, ```), it's best to specify the language explicitly, e.g. ```bash or ```python
    • Note! Add a blank line after the three-ticks-codeblock! (Also two whitespaces after ticks work, but that's unofficial dialect).
  • If you don't want any syntax highlighting, just use ```text
  • For a list of all supported languages see: http://pygments.org/docs/lexers/
  • Give commands, environment variables, command options, as well as partition names between two backticks, i.e. `srun`, `$LOCAL_SCRATCH`, `--gres`, `small`
  • Refer to servicedesk via the docs contact page: as in [contact ServiceDesk](/support/contact/)
    • Page has email, service times, phone, support request how-to

Redirecting pages

  • If there's an URL that has been linked to from the outside a lot and it changes (disappears), a (temporary) redirect can be made
  • Create a file with the name-of-the-old-page.html (or index.html if it was done that way) and as the content:
<!DOCTYPE html>
<html>
  <head>
    <meta http-equiv="refresh" content="1; url='new-page/#anchor-on-that-page'" />
  </head>
  <body>
    <p><a href="new-page/#anchor-on-that-page">Dataset content reorganized!</a>.</p>
  </body>
</html>
  • Edit new-page (and the anchor, if there, otherwise just remove) to match
  • To pass the tests, add the page to tests/python_link_tests/whitelist, too

Terminology

  • When referring collectively to compute servers, use term "CSC supercomputers". Puhti and Mahti should be used explicitly only when needed.

Advanced: page metadata

  • All pages use the site_description metadata by default:
    • site_description: Instructions and user guides for the CSC supercomputers, cloud services, storage and software, including FAQ and tutorials
  • This can be changed per page by adding this to the page top:
---
description: Relevant keywords describing this page
---
  • This may be shown next to the url and title in a google search and this may help in search result ranking.
  • Some discussion on good metadata
  • Examples in docs: support/support-howto.md