Open Daksol opened 2 months ago
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..
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?
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...
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.
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.
I have started a page for this. Contents so far
@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:-
Then two ways of getting that CSS to be invoked
<link rel="stylesheet" href="/stylesheets/cli-doc.css">
extra_css:
- stylesheets/cli-doc.css
<link rel="stylesheet" href="../cli-doc.css">
from affected md filesLet me know. I can include this change in next PR I raise.
Yes, please give the global inclusion a try. We can still revert in the unlikely case it proved to be problematic.
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
VOCABULARY