Skip to content

Instantly share code, notes, and snippets.

Show Gist options
  • Save mbigras/16cbcd8469363689c59573f8d6351d6d to your computer and use it in GitHub Desktop.
Save mbigras/16cbcd8469363689c59573f8d6351d6d to your computer and use it in GitHub Desktop.
Technical Documentation Study - Go Module Tutorial

Technical Documentation Study - Go Module Tutorial

The golang tutorials are so excellent. The tone is very professional and thoughtful, the pace is brisk without being rushed. It really is a breath of fresh air. The formatting is minimal and rarely makes use of inline code, further the lack of syntax highlighting is professional. I think the use of good names and clear authoritative verbs are the heart of why the tutorials are so good. They are such an inspiration!

This document creates the Tutorial: Create a Go module in markdown.

Tutorial: Create a Go module

foo bar baz.

foo bar baz.

foo bar baz.

  1. Clear concept name - zoom in with more details.
  2. bar
  3. baz

Note: This is a useful tip.

Prerequisites

  • Bold idea 1. With some more details.
  • Bold idea 2. With some more details.
  • Bold idea 3. With some more details.

Start a module that others can use

foo bar baz.

foo bar baz.

foo bar baz.

  1. Do this thing.

    On Linux or Mac:

    cd
    

    On Windows:

    cd %HOMEPATH%
    
  2. Do this other thing. Another sentence is needed here.

    In fact, there is more context required so the following example command makes sense:

    mkdir greetings
    cd greetings
    
  3. Paste the following code into your greetings.go file and save the file.

    package greetings
    
    import "fmt"
    
    // Hello returns a greeting for the named person.
    func Hello(name string) string {
        // Return a greeting that embeds the name in a message.
        message := fmt.Sprintf("Hi, %v. Welcome!", name)
        return message
    }
    

    This is a discussion point. This is another discussion point.

    The following explains the code:

    • Declare a greetings package to collect related functions.

    • Implement a Hello function to return the greeting.

      This is more discussion about the above bullet point.

    • How will this image look?

    • Can the image be resized?

This is the end that points to the next tutorial.

What about emphasizing code inside a code block?

  1. Do this step.

    echo hello world
    
  2. Now make this important addition.

    echo hello world
    echo hello world again!

    Wow, strange! It seems like the indentation is 3 spaces not 4. 4 spaces puts a space inside the code block like the next step.

  3. This code block will have a highlighted section but will also have leading spaces

     echo hello world
     echo hello world again!

It works using grip

@mbigras
Copy link
Author

mbigras commented Feb 18, 2021

  • Embed the image in the markdown file in the gist.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment