PITCHME.md 8.3 KB


Linode Docs

Contributing Fixes and New Documentation

https://linode.com/docs/


Overview

The Linode Docs currently contain over 1000 articles.

(1027 at the time of me writing this.)

The topics covered include:

  • The Linode platform
  • Software targeted at Linux servers
  • Deployment tools

Note: and more


Ways to contribute

  • Correct typos and silly mistakes
  • Update existing docs with better alternatives
  • Write a doc

Getting everything in order

  • The Linode Docs are incredibly easy to get up and running yourself.

Hugo and Git Logos

Note: Here comes the git.

+++

Step 1

Fork the repository

Github Fork Button

https://github.com/Linode/docs

+++

Step 2

Clone your forked repository

$ git clone git@github.com:stvnjacobs/docs.git
Cloning into 'docs'...
remote: Counting objects: 43115, done.
remote: Compressing objects: 100% (28/28), done.
remote: Total 43115 (delta 25), reused 21 (delta 14), pack-reused 43073
Receiving objects: 100% (43115/43115), 293.67 MiB | 8.74 MiB/s, done.
Resolving deltas: 100% (29522/29522), done.
Checking out files: 100% (3355/3355), done.

@1

+++

Step 3

Add the Linode Docs repo as a remote repository

$ cd docs/

$ git remote add upstream git@github.com:Linode/docs.git

@[1] @[3]

This will allow you to pull in changes made to the main repository.

Note: Git is set up to be a distributed system.

GitHub just happens to be the "main source of truth" for Linode's docs repo.

By forking the repository, you have created your own copy, hosted on GitHub.

By cloning your fork, you are replicating that copy to your local computer.

But to make changes to our docs, all changes will need go through the Linode/docs repository.

By adding a "remote", we are letting git know that there is another copy of the repository.

We can pull in any changes that are made this repository.

upstream is only a convention.

+++

Confirmation

You can confirm that Linode/docs has been linked with the following:

$ git remote -v
origin	git@github.com:stvnjacobs/docs.git (fetch)
origin	git@github.com:stvnjacobs/docs.git (push)
upstream	git@github.com:Linode/docs.git (fetch)
upstream	git@github.com:Linode/docs.git (push)

$ git pull upstream master

@1 @[2-5] @7

Note: Unless someone made a change in the last few minutes, since you configured the remote, the git pull upstream master should return Already up to date..

+++

$ git branch
* master

$ git fetch upstream

$ git branch -a
* master
  remotes/origin/HEAD -> origin/master
  remotes/origin/config/smart-fractions
  remotes/origin/fix/postgres-pgadmin-link
  remotes/origin/master
  remotes/upstream/cwlinode-patch-1
  remotes/upstream/freebsd_minecraft
  remotes/upstream/install-nginx-ubuntu
  remotes/upstream/master
  remotes/upstream/migrate
  remotes/upstream/nginx-basic-graphic

@[1] @[2] @[4] @[6] @[7] @[8-11] @[12-17]


Project Layout

./
├── themes/
├── README.md
├── netlify.toml
├── docs/
├── CONTRIBUTING.md
├── config.toml
├── CODE_OF_CONDUCT.md
├── ci/
├── archetypes/
├── .vale.ini
├── .travis.yml
├── .gitignore
└── .git/

@[5] @[10] @[9]


docs/

  • Contains all the content files used to compose our documentation.

If you are creating a new doc, or editing an existing one, this is where you will be working from.

Note: Open the GitHub link and show the docs folder

https://github.com/linode/docs/tree/master/docs

https://github.com/linode/docs/blob/master/docs/getting-started/index.md

https://linode.com/docs/getting-started/

We are jumping to archetypes, and skipping CI. We have to write a post first.


archetypes/

Hugo has what they call archetypes.

They are pre-formatted templates for various kinds of posts.

archetypes/
├── default.md
└── content.md

Note: We only write docs, so there isn't much variation, here.

What it gives us, though, is uniformity.

It also let's us set a standard for what metadata is required for new docs.

Show the frontmatter

https://github.com/linode/docs/tree/master/archetypes


The format of a doc

  • Frontmatter
    • YAML
  • Body content
    • Markdown
    • Shortcodes

+++

Frontmatter

author:
  name: Linode
  email: docs@linode.com
keywords: ["getting started", "intro", "basics", "first steps"]
description: 'This guide will help you set up your first Linode.'
og_description: "Learn how to create an account, boot your first Linode, and connect via SSH with our Getting Started guide."
license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)'
modified: 2018-05-23
modified_by:
  name: Linode
published: 2009-07-19
title: Getting Started with Linode
show_on_frontpage: true
title_short: "Getting Started"
weight: 10
icon: "book"
show_on_rss_feed: false

@1-3 @4

https://raw.githubusercontent.com/linode/docs/master/docs/getting-started/index.md

Note: Not pictured

  • Front matter is separated by ---

+++

Body

Hugo, and therefore the Linode Docs, render pages from Markdown.

+++

Shortcodes

Hugo allows for templating of Markdown documents.

One example, used throughout our documentation, are Shortcodes.

+++

Shortcode Examples


Installing Dependencies

$ brew install hugo

Installation docs


Start the Local Development Environment

$ cd docs/

$ hugo server

Submitting a Fix

There are many reasons to fix a guide:

  • It has gone out of date
  • There is some sort of inaccuracy
  • There is a better way to do something

+++

Small Fixes and Typos

Docs Header Edit Link

+++

Larger changes

For larger changes, it is best to open an issue on the GitHub project.

You can still make the changes, but it is best to reach a consensus with the Docs team before putting in the effort to rewrite a large portion of a doc.

https://github.com/linode/docs/issues

+++

Making a branch for changes

It is best practice to make changes on a new branch.

This is more for your own good, as it allows you to keep your master in sync with upstream, while you work on one or more of your own branches.

$ git checkout -b fix/remove-debian7

# fix fix fix

$ git push origin fix/remove-debian7

Creating a New Post

$ git checkout master
$ git checkout -b doc/troubleshooting-ssh

$ hugo new --kind content troubleshooting/troubleshooting-failing-ssh-connections/index.md
archetypes/
├── default.md
└── content.md

https://github.com/linode/docs/blob/master/CONTRIBUTING.md#create-a-new-guide


ci/

The Linode Docs have a test suite that is run as part of a continuous integration pipeline. It test for thing such as:

  • Presence of required metadata
  • File naming and formatting conventions
  • Ensuring there are no broken links
  • Ensuring that all linked images are present

+++

System requirements

  • Python 3
  • Once of Virtualenv, Pipenv, etc. (recommended)
$ cd ci/

$ virtualenv -p python3 .env
$ source .env/bin/activate

$ pip install -r requirements.txt

@[1] @3-4 @[6]

+++

Setting it up

We need two terminals open, so open up a second.

Navigate to the root of the docs directory in both terminals.

Terminal one

$ hugo server

Terminal two

$ ./ci/scripts/blueberry.sh
$ ./ci/scripts/docs404.sh
$ ./ci/scripts/vale.sh

Thanks!