Tutorial Content Creation Guide

  1. Install a browser spell checker!
    It deosn’t mettar how good yuor psot is technicaly, but if it cnotians speling and gramer erors all over the plais, yuor post will be itnreperted as low-kwaliti as the errors in italics on this line demonstrate. :stuck_out_tongue_winking_eye: :crazy_face:

  2. Ensure your post is readable
    This might seem like a no-brainer, but a “wall of text” is not readable, nor are inconsistent italics, Bold small and big font usage. :grin:

  3. Be consistent!
    It doesn’t matter whether you use:

    Big

    # Big

    Medium

    ## Medium

    Extra bold

    ### Extra Bold
    headers to subdivide text, as long as you use the same system throughout your tutorial and please use different sizes for different (sub)sections…
    Even a simple Bold **Bold** like in this Guide is sometimes good enough. :+1:

  4. Use the [Details] section:
    If your post is longer than one screen,

    Click the triangle

    use the [details="Title"] [/details] markdown to hide text that is too long.

  5. Use correct indentation!
    Sometimes it’s just a matter of adding 2 spaces in front of a few lines (E.G. The details section above) to ensure the alignment is correct

E.G. This line is wrongly indented and it decreases the readability of the entire post! :sob:

  1. When writing a tutorial, the first line must contain a difficulty
    Copy-paste this:

    Difficulty: ★☆☆☆☆

    and assign it to a shortcut or whatever you use for automatic comments. Then cut the ★ and replace some of the ☆ with one or more ★ keeping 5 stars in total.

    Click the Triangle to have some more examples
    • Difficulty: ☆☆☆☆☆: Dead easy. I.E. Nothing to install, just run, type or read something
    • Difficulty: ★☆☆☆☆: Just one program to install from the standard repositories, simple tutorial
    • Difficulty: ★★☆☆☆: Just one program to install from the AUR or 2 from standard repositories, simple tutorial.
    • Difficulty: ★★★☆☆: Not for N00bs
    • Difficulty: ★★★★☆: Definitely not for N00bs.
    • Difficulty: ★★★★★: you need to modify the kernel code yourself depending on non-obvious parameters and then recompile the kernel and install it yourself… :man_facepalming:
  2. Be neutral and succintive. E.G.

    • Don’t say: I’ve tested this on my machine with a Z80 and 64 KB of RAM
      but
    • Do say: This tutorial has been tested on a Z80 with 64K
       
    • Don’t say: After a long and tedious testing phase, which involved rain dances, alchemy and astrology, I found out that the discharge setting for the flux capacitor in /etc/flux.cfg had to be set to 1 KiloCochrane per second.
      but
    • Do say:
      • Execute:

        sudo nano /etc/flux.cfg
        
      • Search for the parameter Discharge

      • Change the value to:

        Discharge=1 
        
  3. Please, please, please use the 3 backticks ``` at the beginning and end of multiple lines of code/text or use 3 or more spaces to indent code and don’t put any # or $ prompt because then:

    • a little icon shows up above the command / code that allows the end-user to easily copy the code allowing for less mistakes while copy-pasting! E.G.

      echo "The quick Brown fox jumped over the lazy dog
      

      (Hover over the previous echo command to see this in action!)

  4. Please use Manjaro commands (pamac, inxi) instead of Arch commands (pacman, lspci, …) wherever possible.

  5. Consistently use the <kbd> and </kbd> HTML directives for:

    • On-screen buttons like OK and Cancel
    • Keys on the keyboard like Ctrl+Alt+F2
    • Menu settings that have to be clicked like:
      • File, Print, Settings
      • System Settings, Screen, Compositor
  6. Re-read your post at least twice and edit out any errors you see.

  7. Optional: This is just a gripe of me personally and subjectively:
    Use long-format options when posting for N00bs, please!

Click the triangle to read more on the optional requirement
  • Yes, I know that:
    inxy -Fazyxxx
    is the exact same as
    inxi --admin --verbosity=7 --filter --no-host --width
  • But the former is black voodoo to most N00bs whereas the latter one will tell them that you want:
    • admin parameters,

    • there is lots of information coming

    • Some stuff gets filtered

    • No host information will be given (In this case: host name)

    • Something with width (in this case: wrap lines when reaching end of terminal width)

      Why is this a gripe of me personally you ask?

      Well, In my past I’ve been a *nix admin where the *nix group decided to use the same human operators that the Windows group was using already, so we could have a good night’s sleep instead of being called out of our beds all of the time.
      These operators used to make tons of mistakes as it’s easy to type 1 (one) letter wrong when following a process, but it’s hard to type an entire word wrong, so we standardized on long parameters for everyone .
      That is: for personal use, anyone could use anything they liked, but if you put a command in a script or in a process or a manual you had to use the long version!

      Result: Human Errors went down 90% and some scripts that sometimes misbehaved when Mars and Jupiter were in alignment suddenly had no issues any more! :first_quarter_moon_with_face: :earth_africa:

      :warning: Sometimes using a combination of random letters can form words and some words are quite offensive and some are outright illegal in some countries, so asking for a:

      inxi -Nazi
      

      to let’s say the wrong :de: will ensure you get arrested the moment you cross the German border as it’s illegal to call someone a Nazi in Germany without proof he/she is, indeed, a member of the NSDAP… ¹

:bowing_man:

P.S. For more information on markdown, send a private message @discobot and type start advanced tutorial (or your local language version of that) or have a look over at CommonMark
Note 1: As this is for educational purposes only, what I wrote is allowed though.

19 Likes

Helpful post.

I have one comment for item number 6. I think UI items like menus should be distinguished from buttons. I don’t know if there is a markdown way of doing this.

I searched for an example and came up with asciidoctors user manual menu selection .

System Settings > Screen > Compositor

I just learned this today that a user can look at the raw post. It answers the question, “how’d they do that” :slight_smile: For example: https://forum.manjaro.org/raw/14112/1, where 14112 is the topic id and 1 is the post id. Would it be helpful to create a template that users could start with.

Item number 2, the “#” is semantically known as headers, similar to h1, h2, h3.

Commonmark has a short guide .

3 Likes

Thank you for your feed-back:

It’s just rule #6, so rule #2 Be consistent is much more important. If you don’t like button-shaped menu items: Don’t use them! But using buttons allows me to:

  • System SettingsScreenCompositor

OR

  • System Settings
  • Screen
  • Compositor

depending on my needs

:man_shrugging:

[Edit 1]: Title being replaced by Header right now! :man_facepalming: Thanks for that one too!
[Edit 2]: CommonMark added as a PS on top of the site-specific :robot: tutorial. :innocent:

2 Likes

I’m having a hard time with indentation in this post, doing the advanced discobot :partying_face: training atm after the commonmark 10 minute tutorial.

Using spaces to indent makes it a block quote

The post is not a wiki post yet, is that relevant?

Your tutorial looks good… What do you want to change??? (Also see PM = Personal Message I sent you after I edited that post)

:innocent:

You can use HTML / CSS:

<div style="margin-left: 10px">

       Look! I'm indented!

</div>

Result:

   Look! I'm indented!

Thanks for the tip, it works perfectly with normal text, alas not with the Summary option, unless I’m using it wrong?
Both of the way’s I presume it to have the indent effect:

<div style="margin-left: 10px">

[details="Summary"]

This text should be indented

[/details]

</div>
Summary

This text should be indented

[details="Summary"]

<div style="margin-left: 10px">

This text should be indented

</div>

[/details]
Summary

This text should be indented

Looking at the source it seems the function that does the flip decides that this block needs its own div and strips the extra supplied.

Like this:

<details>
<summary>Summary</summary>
<div style="margin-left: 10px">

       Look! I'm indented!

</div>
</details>

Result:

Summary
   Look! I'm indented!

:bulb: :thinking: I have been phrasing my question the wrong way
I was looking for a way to indent a normal paragraph this way without using a list and preserving the font.

Nah! That doesn’t work!

Markdown and HTML using discourse.org (the software our forum uses) is limited to whatever nokogumbo allows…

:man_shrugging:

An em space can indent a single line of text:

  This text should be indented
    2 x Indented

&emsp; This text should be indented
&emsp; &emsp; 2 x Indented

A paragraph following a list item (bulleted or numbered) can inherit the list item indent:

  • Space

    Space is big. You just won’t believe how vastly, hugely, mind-bogglingly big it is. I mean, you may think it’s a long way down the road to the chemist’s, but that’s just peanuts to space
* Space</br>
Space is big. You just won't believe how vastly, hugely, mind-bogglingly big it is. I mean, you may think it's a long way down the road to the chemist's, but that's just peanuts to space

If a space after the list item is not needed, subsequent lines only need a single space for indentation:

  1. Time
    Time is an illusion
    Lunchtime doubly so
2. Time
 Time is an illusion
 Lunchtime doubly so

But I have not come across a way to indent a single paragraph

2 Likes

@Fabby

Hi I am learning markdown, but observe the following so forgive me for any pedanticness

If I type <kbd>Shift without closing it with </kbd> its not a button.
beginners like me, reading above tutorial may fall into that trap.

Could you consider edit?

Extra question because you are so nice :smiley:
How do I find the tag for this forum post.
When I search for tag=markdown I see only one post

Yes I can now read and see it links to Tutorial Content Creation Guide but this Guide does not appear to be tagged itself.

The Dr wants me to take smarter pills so I hope you understand I am suggesting that above post should be tagged. Or am I missing something.

thanks for reading.

Now I know what its called, I do agree its a sticky in the tutorials forum but I was stumped with my brain fade earlier.

1 Like

I think you can remove the backquotes here: now Discourse copies the whole format on selected text, so the backquotes are also copied.

1 Like

Thank you for the topic!

  1. Why the current edition of teaching post was designed in the way that brakes it’s suggestion of third item at least in 2.5 times (with default page zoom of FullHD resolution, with no additional desktop panels usage)?

  2. I saw many topics used [HowTo] prefix. Did somebody measure how search engine of this forum and global Internet indexers lowers such topics in result list instead of using “how to”? Why to restrict Manjaro forum to be a one of global answers provider in the same time with serving community requests? Currently I created 2 topics and all of them not only Manjaro related, but much wider (systemd journal and DE-related). Nobody want their publication to be useful globally also, not only on Manjaro forum? It is perfect that we have Tutorials section opened for crawlers, but in tiny details we can do more: to serve global requests also.

3 Likes

Sorry for the late answer… New job interfering with time… :man_shrugging:

  1. Were you drinking again when you posted that? :grin:
    I don’t understand what you’re asking

  2. No, but if you do, I’d be interested in your results. :+1:

    See #1 above :stuck_out_tongue_winking_eye:

    Thank you! Please continue doing that!

:handshake:

1 Like