Skip to content

Project management | Create Documentation

This first week I worked on getting used to the documentation process.

For this assignment I created a repository which includes a page (the one your are reading right now).

Softwares

- For Control Version we used GitLab with GitBash.
- For documentation structure we used Markdown.
- For code edition I used Visual Studio Code.

GitLab

Create an account

  • Go to GitLab.

  • Register a new account, the easiest way (and the one I used) for that is Create an account with Google:
    Create account

  • Continue to accept the Terms of Service and Privacy Policy.
    Account already done! Welcome to GitLab:
    Account created!

Create a new project

  • New > New project > Create blank project:
    Create new project

  • Fill in Project name.
    Project slug is what the GitLab instance will use as the URL path to the project and it’s automatically filled with Project name, if you want to personalize it you can edit it.

  • Write a Project description (optional).

  • Set the Visibility Level preferably as Public, this will be applied to all of our [ future ] files and pages

  • Create project:
    Create new project
    New project created:
    New Project Created

Once we already have our page files (most important, the .gitlab-ci.yml) in GitLab, GitLab we go: Projects > SelectTheProject > Settings > Pages

GitBash

Installation

- Git for Windows

- Git for MacOc

- Git for Linux: $ apt-get install git or “yum install git”

When Git is downloaded, we get GitBash for command line, and GitGUI which is a more graphical version. We are going to work with GitBash.

Note: I’m currently using Windows.

Settings

  • Open GitBash.
  • Add username: $ git config --global user.name "your_username"
  • Add email address: git config --global user.email "your_email_address@example.com"

Something like this:
Git Setting

Authentication | SSH-KeyGen

To connect our computer with GitLab, we need to add our credentials to identify ourselves.

  • Open GitBash

$ ssh-keygen -t rsa -C "your_email_address@example.com"

  • Press Enter until it says “The key’s randomart image is:”:
    Git Setting

  • Open GitLab > Account > Settings > SSH Keys > paste there the content of the created file:
    Git Setting

Clone a Repository

There are two main options to create our web sites: use HTML or Markdown. This time I chose Markdown, cause I rather focus my time more on creating a useful documentation, then I’ll be using the Markdown FabLab Template which already have an space for the Assignments.

  • Open the folder in the PC where you are going to work

  • Right CLick > Git Bash Here

For cloning use the command git clone <repository path to clone>. We can either clone it via HTTPS or SSH (the one I used)

For getting the path: Open Git repository to clone > Clone:
Git Setting

Cloning via HTTPS: git clone <https://gitlab.com/satshas/template-test.git>

Cloning via SSH: git clone <git@gitlab.com:satshas/template-test.git>

Something like this:
Git Setting

Basic commands

After cloning, we mainly need the next commands:

-To locally create a repository with GIT: $ git init

-To indicate the status of the repository; modified, added and deleted files: $ git status

-To add to the repository ALL files and folders that are in our project: $ git add -A

-To commit the files that have been modified and GIT: $ git commit -m "add_a_message"

Note: Afterwards the message will allow you to know exactly what modification you made in that commit.

-To upload the files to the remote repository: $ git push -u origin master

Markdown

Markdown is a lightweight markup language to add formatting elements to plaintext text documents.

These are the files with the extension *.md

Some Basic Markdown syntax for editing your documentation:

Element Description
Heading # H1
## H2
### H3
Bold bold text
Italic _ italicized text _
Blockquote > blockquote
Image ![alt text] (../images/image.jpg)
Link [title] (https://www.example.com)

Code editor

Visual Studio Code is a source code editor developed by Microsoft for Windows , Linux, and macOS:
VisualStudioCode

This is the Code editor that I personally like to use, includes Page preview for checking how your page is generally going to look like, and also Git commands built-in.

Git Commands:

To Add changes: Source Control > Views and more actions > Changes > Stage all Changes.

To Commit: Source Control > Views and more actions > Commit > Commit all.

To Push: Source Control > Views and more actions > Push.

SourceControl


Last update: February 12, 2021