Documentation Style and Vocabulary Guide`

[Daksol]

A few simple rules or preferred vocabulary would aid consistency in documentation. These are a few I am trying to follow. Any additions, corrections?

No particular order:

FORMATTTING

• File extensions
  • Refer to them in upper case, so JPG, FLAC, GIF

VOCABULARY

• The Library
  • Refer to as the Media Library following how it is referred to in Settings (and not Music Library)
• The folder containing the Library
  • Settings calls this "media folder"
  • Checking more carefully in CLI documentation I see I have incorrectly emphasised the alias 'musicfolder' database CLI command rather than the preferred option of 'mediafolder'. A comment in Request.pm source file says "# musicfolder is only here for backwards compatibility - it's calling mediafolder internally". I will fix that. https://lyrion.org/reference/cli/database/#musicfolder
• Music files
  • Refer to them as Media Files (not Music Files)
• Talking about LMS
  • Refer to the LMS Server rather than LMS Software

[terual]

With respect to abbreviations: agree

But the second point is debatable. Logitech Media Server used to support more than music (also pictures and video I thought), but support for those media has been removed from LMS. That is why during the name change Lyrion Music Server has been chosen. It only follows if we do that consequently, so we should refer to the Music Library, etc..

[terual]

Also I think it would be good to adhere to the Microsoft Style Guide, as they have thought a lot about capitalization etc.. Maybe we can leverage Vale when the documentation grows a bit more?

[michaelherger]

Why not define the style guide as part of the documentation, where it can be revised, versioned etc.?

As for the extensions my gut feeling would be to use lowercase if it's the extension, but uppercase when referring to a file type...

[Daksol]

Why not define the style guide as part of the documentation, where it can be revised, versioned etc.?

Agree - yes.
In same place or alongside we can include notes on the various CSS magic in tables - colspan, preventing wordwrap on code items.

[Daksol]

Also I think it would be good to adhere to the Microsoft Style Guide, as they have thought a lot about capitalization etc.. Maybe we can leverage Vale when the documentation grows a bit more?

Thanks for those references I will take a look.

[Daksol]

I have started a page for this. Contents so far

• Proposed location:
  • /reference/editingthisrepo/editingnotes.md
• Contents of page:
  • vocabulary - as per notes above
  • style guide - thus far limited to referring to Microsoft Style GUide
  • formatting work rounds
    • merging cells in a table row with inline html+css
    • prevent wordwrap of code elements in a table column

[Daksol]

@mherger
When writing up the note on the "prevent wordwrap of code elements" it occurs to me that this capability may be needed in places other then the CLI folder - which is current location of the CSS file,

Suggest that it would be better to see the CSS file in a defined location relative to the file system root, to keep things stable in longer term.

Squidfunk do suggest a location for CSS files, and explain how to give them repo-wide scope. as per this page.

So propose changes:-

• Relocate existing CSS file (cli-doc.css) to new directory /docs/stylesheets/

Then two ways of getting that CSS to be invoked

• Option ONE, file by file
  • update CLI md files where the css is invoked to use this link <link rel="stylesheet" href="/stylesheets/cli-doc.css">
• Option TWO, make the CSS apply to how all files in repo are rendered
  • seems a reasonable option, cannot see how code strings being set not to word wrap will do much harm. Simplifies instructions to editors.
  • add these lines to mkdocs.yml (following squidfunk's instructions from linked page above)

  •    extra_css:
        - stylesheets/cli-doc.css
    

  • and eliminate the existing line <link rel="stylesheet" href="../cli-doc.css"> from affected md files
  • I have tested this on my setup, seems to work fine

Let me know. I can include this change in next PR I raise.

[michaelherger]

Yes, please give the global inclusion a try. We can still revert in the unlikely case it proved to be problematic.