Writing Conventions for Markdown-based Docs

[nelsonic]

When writing a "how-to" (e.g: learn-xyz) or general project documentation, should we have a list of writing conventions the way O'Reilly books (the benchmark for tech books) always have a "Conventions Used in This Book" section at the start of the book e.g: http://www.oreilly.com/openbook/debian/book/prf1_02.html

Terminal Commands

When instructing people to run a certain command in the Terminal (Emulator), should we

• include the $ (dollar sign) in front of the command (or not) ? #discuss
• explicitly state that the command has to be run in the terminal?
• use constant width bold for all "Commands or text to be typed by the user" ?

For a complete list of the O'Reilly Typography and Font Conventions see: http://chimera.labs.oreilly.com/books/1230000000969/ch03.html PDF Snapshot: O'Reilly-Typography-and-Font-Conventions.pdf

[mk4111]

@nelsonic, here are my thoughts!

• The $ sign isn't mentioned in the O'Reilly conventions, but I personally think it makes clear to the reader, that this is what we expect to see on the terminal.
• I think explicit statements make things obvious, but they could be omitted by providing a link for people who are unfamiliar with dwyl conventions at the top of each README.md. That said, it might be a deterrent from just diving into the tutorial, because they have that much more to read... In which case, maybe explicitly stating is a more 'encouraging' solution...
• I like the constant width bold for commands to be typed by the user!