14
$\begingroup$

The basics are explained in formatting help, but perhaps for sake of homogeneity we can adopt a style guide concerning conventions with examples of how to and not to mark-up content.

Well established Exchanges rigorously enforce their style-guide, this doesn't mean people lose their identity but it does mean that people combing through the site can quickly understand the content, without having to parse through various personal styles.

We may not all agree with some of the conventions, so I will reference appropriate examples in these cases. The following is a work in progress, feel free to add your suggestions and objections in the comments or as answers.

Style Guide

  • Avoid using bold to emphasize key words mid sentence, using bold rarely has the effect you think it does.
  • Use back-ticks for short code references only.
  • Use the kbd tag only when referencing keys or mouse buttons. Menu / submenu items should perhaps get their own tag type if possible (with own styling).
  • If you inline an image, make sure to crop when possible or otherwise edit it before uploading. Edit it in a way that most of it's pixels contribute to passing information.

Please discuss the following.

Menus

we should pick one and stick with it, encourage new users to conform.

  • Add > Mesh > Cube
  • Add → Mesh → Cube
  • Add > Mesh > Cube
  • Add > Mesh > Cube
  • Add > Mesh > Cube
  • Add > Mesh > Cube
  • Add | Mesh | Cube
  • Add > Mesh > Cube
  • Add|Mesh|Cube
  • Add | Mesh | Cube
  • Add → Mesh → Cube
  • Add→Mesh→Cube
  • Add | Mesh | Cube
  • Add > Mesh > Cube

I will argue for the first option, it is undeniably easier to type while still serving the author and the reader well. edit: This has generated some interesting discussion and style proposal

keyboard shortcuts (and mouse events)

This one is not be up for debate, it seems we all accept the convention to use the kbd tag. One might find slight variance in the following.

  • Ctrl M
  • Ctrl + M
  • CtrlM
  • Ctrl + M

Cases for all three can be argued, I will stick up for the last as it seems to be most visually straightforward.

Links

This may be somewhat tricky, but here we find less variety than the menu items. Also the meta has slightly different styling than the main site so this may fail to serve the point I wanted to make.

Again with the first example being easiest to type, but I will agree the styling fails to significantly distinguish short links, the dark blue and black are not easy to tell apart on the main site -- I suspect this is the main reason people feel they should decorate their links with other methods.

to be continued

more to come (sorry had to cut short)

$\endgroup$
18
  • $\begingroup$ is "Menu / submenu items should perhaps get their own tag type if possible (with own styling)." an existing feature of stack exchange? if not maybe make a feature request on the meta $\endgroup$
    – user235
    Commented Aug 16, 2013 at 12:08
  • $\begingroup$ I posted a question on meta for the menu item formatting What is the markdown for menu options $\endgroup$
    – user235
    Commented Aug 16, 2013 at 12:27
  • $\begingroup$ good man! feel free to help flesh out this post too. $\endgroup$
    – zeffii
    Commented Aug 16, 2013 at 12:32
  • 1
    $\begingroup$ Aldrik won't like the third one :( $\endgroup$
    – wchargin
    Commented Aug 16, 2013 at 14:40
  • $\begingroup$ I would say menu options should be **Menu** → **Submenu** → **Menu item**, whereas non-menu UI elements are *Render Engine* or *Remove Doubles*. $\endgroup$
    – wchargin
    Commented Aug 16, 2013 at 14:52
  • 2
    $\begingroup$ whatever we settle on, it's something all of us should be doing else there's too much disparate styles $\endgroup$
    – zeffii
    Commented Aug 16, 2013 at 15:02
  • $\begingroup$ @WChargin Fear not, I am rather amused. ;) @zeffii The available markup already has documented semantics that apply, e.g if someone wants to emphasize something they should use the <em>, <strong> or the markdown equivalents. There's also the issue of enforcement. Looking about it seem that users shouldn't be badgered about markup. $\endgroup$
    – Aldrik
    Commented Aug 16, 2013 at 16:22
  • $\begingroup$ hey, if it's just me being fussy about this nothing's going to change, $\endgroup$
    – zeffii
    Commented Aug 16, 2013 at 16:34
  • $\begingroup$ @Aldrik, actually, if you read the accepted answer, you would see that these are seen as being odd. It would be best if our site adopted a conventional style of markdown instead of everyone doing what they felt like or what external sources say they should be used for. Sometimes it looks messy and I agree with the answer on that question that these should often be edited when possible. Menu options should be something like Object > etc. This isn't a large site (yet) like SO so these things get noticed and aren't as minor as some might think. $\endgroup$
    – iKlsR
    Commented Aug 16, 2013 at 17:37
  • $\begingroup$ Indeed, in that case it's odd because of the incorrect usage. The web standards aren't just some other site, what they decide upon is how it implemented in all web browser, robots/search-engines and user accessibility tools, etc. If you don't like the styling, that's a different issue. It's my understanding that will be changeable once we're out of beta. $\endgroup$
    – Aldrik
    Commented Aug 16, 2013 at 17:55
  • 2
    $\begingroup$ Looks good. For menus I would recommend going with Menu Item > Submenu Item or Menu Item > Submenu Item. I prefer using italics, but it depends on what the rest of you guys think. $\endgroup$
    – CharlesL
    Commented Aug 16, 2013 at 17:59
  • 1
    $\begingroup$ Also, when formatting shortcuts, is it necessary to use a '+' in between? The styling already separates the two. $\endgroup$
    – CharlesL
    Commented Aug 16, 2013 at 18:02
  • $\begingroup$ perhaps what we could do is pick issues, write about them as answers and people can discuss them seperately -- else this comment section gets long and it doesn't allow much formatting anyway. $\endgroup$
    – zeffii
    Commented Aug 16, 2013 at 18:25
  • $\begingroup$ @Aldrik the main issue we have is that SE renders these badly, line consistency is lost and pipes with <kbd> is ugly.. some more issues are brought up on the meta.so post I think. $\endgroup$
    – iKlsR
    Commented Aug 16, 2013 at 18:59
  • $\begingroup$ @CharlesL okay, but why no right arrow &rarr;? it looks much cleaner from my point of view. $\endgroup$
    – wchargin
    Commented Aug 17, 2013 at 1:28

2 Answers 2

Reset to default
7
$\begingroup$

Excellent post, I think there needs to be a consistent style-guide. These should be as clear as possible so here are my suggestions:

Menu Items

  • Add > Mesh > Cube is very easy to type, it gets the point across and provides a logical flow of operations as the brackets hint that each item flows into the other as opposed to listing and separating items with pipes. Italicizing these also separates it from the rest of the content and that is enough.
  • For menu items that have entries in the manual, these can be linked in if you deem it necessary.
    Example: Add > Mesh > Cube.

Shortcuts

  • There should only be one word on each button so either of these can be used interchangeably.
    Example: CtrlShiftM and Ctrl + Shift + M are perfectly fine as long as they are chained together in the correct order.

Links

Images

Other

  • I agree that we should use back-ticks sparingly and only for code, filenames, extensions, parameters/arguments and links to the api for functions. Don't use this for mere highlighting purposes.
  • Using <kbd> for menu items not only makes the line height inconsistent for the post but it also makes the words smaller than they need to be. Here is another good reason why this shouldn't be practiced and another meta discussion on this.

I will further update this answer as you update your question.

$\endgroup$
6
$\begingroup$

What about using something similar to the wiki, especially for mouse actions? (I've had to explain what 'MMB' or 'RMB' etc. stand for occasionally).

For example:

Shift + MMB (<kbd>Shift</kbd> + ![MMB][MMB])

AltRMB RMB (<kbd>Alt</kbd><kbd>RMB ![RMB][RMB]</kbd>)

AltRMB RMB (<kbd>Alt</kbd><kbd>![RMB][RMB] RMB</kbd>)

CtrlShiftMW (<kbd>Ctrl</kbd><kbd>Shift</kbd><kbd>![MW][MW]</kbd>)

Ctrl LMB (<kbd>Ctrl ![LMB][LMB]</kbd>)

⌘ Cmd⌥ OptQ (<kbd>⌘ Cmd</kbd><kbd>⌥ Opt</kbd><kbd>Q</kbd>)

⎈ Ctrl⎇ Alt↹ Tab (<kbd>⎈ Ctrl</kbd><kbd>⎇ Alt</kbd><kbd>↹ Tab</kbd>)

⇧ ShiftD (<kbd>⇧ Shift</kbd><kbd>D</kbd>)

Since this is kind of a pain to type out, I'm thinking of modifying the kbd script to do this automatically. I have modified the kbd script to do this automatically now.

@David does this work: ⎈ ⎇ ?

$\endgroup$
6
  • $\begingroup$ I think the short-name of the mousebutton should always be added, otherwise it is hard to distinguish between MMB and MW. I know that the tooltips show the full name of the MB, but relying on tooltips is IMHO a PITA. $\endgroup$
    – Ocaso Protal
    Commented Jul 3, 2014 at 10:50
  • $\begingroup$ @OcasoProtal Good point. Do you think the order matters? e.g. MMB ![icon], or ![icon] MMB? I originally was thinking the first way, but now that I think about it, the second way would be more consistent with the modifier key formatting. $\endgroup$
    – gandalf3
    Commented Jul 3, 2014 at 21:13
  • $\begingroup$ Looking at the modifers I would also prefer the second way. $\endgroup$
    – Ocaso Protal
    Commented Jul 4, 2014 at 6:34
  • $\begingroup$ The Unicode characters you have for "Ctrl" and "Alt" are not displaying in Firefox 31 on vista $\endgroup$
    – David
    Commented Aug 17, 2014 at 2:37
  • $\begingroup$ @David Works fine for me here, FF 31 Archlinux. Maybe a font issue? $\endgroup$
    – gandalf3
    Commented Aug 18, 2014 at 2:20
  • $\begingroup$ @David Does it work if I use an html decimal entity instead of pasting the character itself? See edit (It seems they don't work in comments). $\endgroup$
    – gandalf3
    Commented Aug 18, 2014 at 6:24

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .