My Habits for Writing Clearly on Discuss


#1

I’ve wanted to write this for a while, but I’ve had other things to do … but now I’m inspired, so here’s a brain dump …

There are a few things I’ve learned for communicating well on Discuss. And since Discuss runs Discourse, most of these will probably be transferrable to any Discourse-based board.

Oneboxes

If there is one thing that I want people reading this to take away from this post, it is the awesome Onebox feature of Discourse. Oneboxes is the feature that turns any link in a paragraph by itself into a nicely formatted card with an icon a link with title and a preview, automatically generated from the content at the other end of the link! Discourse supports all kinds of Onebox links too:

Links to posts or topics:

https://discuss.atom.io/t/atom-roadmap-to-1-0/12379

Links to GitHub Issues:

https://github.com/atom/atom/issues/3684

Links to YouTube:

https://www.youtube.com/watch?v=dQw4w9WgXcQ

You don’t even have to leave Discuss to get Rick Rolled :laughing:

And plenty more! Next time you want to post a link, try it on its own line and see if it oneboxes … I think it makes things easier.

Markdown

Discourse accepts Markdown in all message fields, just like GitHub. So getting used to using Markdown is going to help you immensely, both on Discuss and in communications on GitHub (like bugs, pull requests and the like).

Keyboard Shortcuts

Keyboard shortcuts are discussed here frequently. I’ve found they are immensely easier to read when formatted properly using the <kbd> HTML tag. So <kbd>Ctrl+Q</kbd> becomes Ctrl+Q. Additionally, I feel like the following rules make keyboard shortcuts easier to understand:

  • Modifier keys are written in their common abbreviation with an initial capital
  • Modifier keys are always written in the following order: Cmd/Meta/Windows, Ctrl, Alt, Shift, Fn/Hyper/Menu
  • Keys that are meant to be pressed together are joined with a +
  • Keys (or key combinations) meant to be pressed separately are separated by a space
  • All other keys are written in all caps

Inline Code

Now, if you know Markdown, you know that inline code is delineated by backticks ```. I don’t just use it for code, but for anything that might be misunderstood because of character similarities such as:

  • I for l for 1
  • O for 0
  • 8 for B
  • etc

Code Blocks

So, most people know you can place a code block in Github-Flavored Markdown by using triple backticks on lines by themselves:

```
The code goes here
```

But what is less well known is that you can put the name or abbreviation of a language after the first set of backticks to get syntax highlighting too! So this:

```coffee
foo = 'foo'
```

Becomes this:

foo = 'foo'

Pane move down (ie without splitting)
Web-frame module not found
Error message - how to get rid?
Building done and testing failed
How to write Code Blocks
How to have Atom close HTML tags by itself?
Announce - Navigate Package - Forward/Backward into files
Indented soft wrap
Anyway to theme DEV Console of atom?
Cordova browser app as Electron Desktop App
Snippets not working on windows 7
Multi Background Colors for Different Scopes
Snippet works, but shortcut never seems to
#2

Thanks, I was wondering how to do the Oneboxes!


#3

+1 for the rick roll. It’s been a while :stuck_out_tongue_closed_eyes: