How to Write a Guide

INTRODUCTION

Every guide needs to follow some rules and guidelines to ensure quality content and ease-of-use for all Linux Academy students.

The editor toolbar contained at the bottom of the guide writing text box, includes the formatting options needed to style your guide appropriately.

SECTIONS

Every Linux Academy Guide should use sections to segment each portion of the guide. Use the 'A' button in the editor toolbar to select "Header 1" for each section title.

You can also make sub-sections by selecting the "Header 2" option, under the 'A' button. Sub-sections help to divide up larger tasks contained in a single heading.

Required Sections

Each guide should have an "Introduction" section describing the basic goals of the guide. It should make clear what skills and topics the guide covers, and should be short and to-the-point.

Different stages or steps of the guide should then have their own sections, splitting up longer tasks into sub-sections.

You may also want to include a section about "Next Steps" the reader can take to study the topic further and learn more.

Section Order

When you write a guide, you should think about the order of your sections. Is this the most logical order for a new reader to follow, or just the order that you happened to write your guide?

Images

Feel free to upload images if they help to illustrate your guide, but do not add images if they do not add any value to the guide. Do add images if they make your guide more complete and enrich your readers' understanding.

Grammar

Try to write in clear language that follows the standard practice of your language. Remember to check the spelling of your words, and reread through your work before posting. Websites like grammar.ly and hemingwayapp.com can assist in editing English-written guides.

Code Snippets

Linux Academy's community pages support some syntax highlighting for code snippets. To activate the highlighting:

  1. First, write out your code in the editor of your choice.
  2. Next, paste your code into your guide, selecting the 'Format as Code' option from the box that appears on the screen.
  3. Highlighting will take effect on the next page load.
You should end up with something like this:

var myObject = { 
init: {
alert('You called "init" on a myObject');
},
}

var instance = new myObject();
instance.init();

Sources / Plagiarism

Please cite your sources at the end of your guide. Additionally, if there are websites where you can download software, please put a set of links a the end of the article, so that people can quickly locate all of the materials needed to use your guide.

Additionally, all guides are checked for plagiarism.

  • post-author-pic
    Terrence C
    10-26-2016

    Thanks for the great summary!

  • post-author-pic
    Aj N
    10-26-2016

    Nice guide!

  • post-author-pic
    Christopher B
    10-31-2016

    Additionally, you should always test run your guide word for word to make sure the laymen can follow it.

  • post-author-pic
    Dmitry K
    11-10-2016

    Hello,


    Seems link to hemmingwayapp.com broken

  • post-author-pic
    Kirk V
    11-10-2016

    Is it alright to include a highlighted screenshot for code snippets? The green of my terminal makes the font stand out more, and just wanted to see if it's ok.

  • post-author-pic
    David S
    11-11-2016

     @Promotethetux  I would prefer to have it set as text, and marked as 'code' as outlined above, so that our syntax highlighter can parse it. Also if it is text and not a screenshot then people can copy it more easily, which is often very helpful. If it is text, we can, furthermore, revisit some of the styling components of the website to make it pop a bit more. That said, if it illustrates something that you are trying to explain, and the screenshot just makes more sense, do not hesitate to use it.

  • post-author-pic
    David S
    11-11-2016

     @dkorzhevin I have fixed the broken link. Thanks!

  • post-author-pic
    Aj N
    11-22-2016

    Hi  @culhwch . Because a guide can be lengthy and requires a lot of editing, it would be great to have different states "published" (save & share) and "unpublished" (save without sharing) as well as a preview function.

  • post-author-pic
    David S
    11-22-2016

    Hi  @AJNOURI 

    Great suggestions. We will definitely consider them!

  • post-author-pic
    Francisco S
    11-22-2016

    And an "auto save" feature will be awesome too. Not like Wordpress with multiple revisions and history. Only something like "save every 1 minute or something". WebSockets to the rescue!

  • post-author-pic
    Sigurd S
    11-26-2016

    I would very much like to learn code. Expecially Java, C++ and python. 

  • post-author-pic
    David S
    11-28-2016

     @Sigurdsk We have courses for Ruby and Python available. Check under the "Linux" category.

  • post-author-pic
    Arman K
    03-31-2017

    Hi @culhwch I wrote this guide recently. Formatting looks decent when the user is logged in. With external sharing link, it doesn't go well. Can you guide on this?

  • post-author-pic
    Aby C
    07-24-2017

    Thank you for posting this guide!

  • post-author-pic
    Jose L
    10-28-2017

    Thanks for the guide.

  • post-author-pic
    Aleks T
    11-23-2017

    Valuable info!

  • post-author-pic
    Sam Q
    12-29-2017

    Great, thanks!

  • post-author-pic
    Paula S
    04-25-2018

    Thanks for clear directions!

  • post-author-pic
    Adam H
    08-10-2018

    Hello! It is good article, thank you a lot! Manuals is very important (especially correct manuals!). My business had few mistakes in it, so, we decided to try  http://www.manualwriting.net/our-manual-writing-services/best-user-manual-writing-help/ and it helps.  
    Maybe this information will useful for someone. I know that it is not only our problem, so lets help each other with tools).  
    It is hard to give this task to another person, who can broke your business or reputation. So, you can try this one. (I use it because really do not have enough time).
    So, I recommend if you are want quality))  


Looking For Team Training?

Learn More