2

I'm researching software instruction conventions. This is specifically for training slides and materials, though I'm interested in your preferences for Tridion Stack Exchange and other online locations.

Discussion Topic: What are your preferences for capitalization, font, and style when explaining (or learning about) SDL Tridion?

Example from SDL Live Content which uses bold for terms:

  • On the Home tab or the Create tab of the Ribbon, click New Component. A New Component window appears...

I've also seen single quotes (') for terms as in:

  • On the 'Home' tab or the 'Create' tab of the Ribbon, click 'New Component'. A 'New Component' window appears...

Of course we have markdown's backtick (`), which would translate to a different style in a document.

  • On the Home tab or the Create tab of the Ribbon, click New Component. A New Component window appears...

Things to consider:

  • When to capitalize terms (e.g. is there a difference between a (Tridion) page and a conceptual "page?")
  • Separator for folders?
    • 020 Global Content > Building Blocks
    • 020 Global Content / Building Blocks
    • 020 Global Content \ Building Blocks

The important part is consistency (and maintainability) rather than a specific format. Feel free to add examples and reasons for conventions. No guarantees on what the team will actually use, but if you ever see your standard in a future training, feel free to tell the class it was your idea. ;-)

1 Answer 1

Reset to default
1

By Midas Rule I'll try lining up with our documentation. We currently use:

  • Chevrons as separators (Menu > Item)
  • Bold without quotes, for UI elements
  • Courier for code, user input, and file names/paths
  • Variables in italic
  • Consistent approach to diagrams (i.e. following the "Carbon" theme)

Thanks to SDL Live Content's technical writers for making this part easy.

Feel free to add comments, feedback, examples, or even pet peeves.

4
  • 2
    I agree to this, but personally would love if everybody would just start with adding some form of markup or punctuation to their questions/answers as sometimes I find it so hard to read a random blob of text (no offense meant to anybody here).
    – Bart Koopman Mod
    Commented Sep 5, 2013 at 10:24
  • Is that where my downvotes are coming from? I was wondering who I was offending with long block of text that go on and on, even though I swear I've answered or asked correctly with enough detail that even Mr. P can't say anything. Usually I put in bullets and numbers and headings to make it legible, but I'm thinking the creators of Stack Exchange put a limit on comment boxes to prevent random blogs of text instead of entire blog posts in such a tiny text box. Which is an intriguing point for my next content modelling session and the meaning of text field line heights in authoring forms. I'll..
    – Alvin Reyes
    Commented Oct 1, 2013 at 8:22
  • Got cut off. I meant to say that I'll definitely try better (oh and I know you didn't mean me, per se). :-) +1 to the comment!
    – Alvin Reyes
    Commented Oct 1, 2013 at 8:24
  • 1
    I don't downvote a post if I can fix it by editing, a downvote is really saying it is not useful, so beyond repair. Being a moderator I'd probably sooner delete it than downvote it. But back to the point, I myself am also at fault of writing too long answers,but then I'll just keep on saying: It's not the size that matters, it's whether you make it readable ;)
    – Bart Koopman Mod
    Commented Oct 1, 2013 at 8:30

You must log in to answer this question.

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