How to Add Images to a Github Wiki Without Uploading

Unlike regular documentation created past the Product Managers, Github Wiki documentation aims to describe the application in equally granular detail as possible. The goal is to express the application targeted towards developers in an easily accessible unmarried source of truth.

Purpose

The reason nosotros write in the Github Wiki is to help the onboarding process of new developers and decrease the amount of "gotchas."

A standard squad rotation takes up to a month to fully onboard a developer. Writing this technical documentation allows making the rotation process efficient and repeatable thus yields a high render over investment.

This technical documentation also saves fourth dimension during project handovers and increase the value of the product we deliver to our clients.

Time allocation

Whenever completing an ballsy or sizable feature, be sure to allocate some time to write documentation.

There are other cases like when adding a third-party service or cron task that requires explanation, simply that is on a case-by-instance footing. Ultimately, all details worth explaining in terms of the application functionalities would be in the Github Wiki.

Organization

Documentation has to follow a standard structure for consistency beyond projects. The mandatory sections are the following:

Home
Getting Started
Compages Section
Infrastructure Department
Operations Section

Below is an example of what information technology could contain:

            ├── Home ├── Getting Started / Project Setup ├── Architecture │    ├── Authentication Flow │    ├── Assistants │    └── ... ├── Infrastructure │    ├── Cron Jobs │    ├── Deployment Procedure │    ├── Environment Variables │    └── ... ├── Operations │    ├── Debugging │    ├── Testing │    └── ...

Dwelling house

This section contains a general summary of the project and background information virtually the awarding. It likewise briefly explains any specific terminology used in the application.

For instance:

Home Wiki Example

Getting Started

More technical project setup information is in this section. This section comprises of:

Environment version requirements
Prior tooling required
Any data that helps setting up the development environment in a usable state. (East.g. Inserting examination accounts, generating required secret keys.)

Usually, the format of this section is consequent with other projects.

Architecture

This section contains any Architecture Determination References (ADRs) and explanations of the loftier-level awarding menses.

All sub-headings are specific awarding flows on the awarding. These sections are where we place all awarding features and functionalities.

            # Examples ├── Architecture (ADRs and high-level diagrams) │    ├── Registration │    ├── Payment Flow │    ├── Admin Section │    └── ...

Infrastructure

This section involves whatever prior application setup that requires caption, such as CI/CD, secrets direction, localization, and ongoing cron jobs.

It is primarily to assist developers understand the proper setup and deployment of the awarding.

            # Examples ├── Infrastructure (Cloud/Hosting Infrastructure Diagram) │    ├── Ongoing Cron Jobs │    ├── Deployment Process │    ├── Environment Variables │    ├── Localization │    ├── Secret Management │    └── ...

Operations

Whatsoever activity that volition ensure the smooth running or maintenance of the application goes here.

This section gives an overview of administrative tasks that are pertinent to the running of the application. Subheadings commonly comprise helpful debugging procedures, testing helpers, or mock data used in tests.

            # Examples ├── Operations (Overview of important tasks) │    ├── Running Tests │    ├── Running Docker tests on the CI │    ├── Automated Code Review Setup │    ├── Debugging │    ├── Testing │    └── ...

An case wiki we've fabricated can be institute here.

Merging Documentation

Creating New Documentation

After merging a feature branch, work on the documentation branch.
Submit a PR for the documentation branch to be reviewed.
On approval, merge the documentation branch to development.
Configure the CI so that it automatically publishes the documentation to the Github Wiki via a Github Activity. Discover more information about this step here.

Documentation Review

Reviewing documentation is similar to regular pull requests. There are other guidelines we should follow to meet standards.

Ensure all content is formally written in the active voice.
Pay extra attention to grammar and punctuation. Use a grammer-checker such as Grammarly.
Ensure the target audition of the documentation is aimed towards developers with a limited agreement of the project.
As there are many opinions on carrying the same message, aim to resolve discussions quickly.

Nugget Direction

Calculation Images

By default, the text editor for Github wiki does not support image uploads and would require hosting images elsewhere. But Github wikis are regular git repositories, so information technology is possible to add avails past:

Clone the repository to your local motorcar
Add together all images under the assets/images/ directory

            .github/ |  └── wiki/ |       ├── Home.md |       ├── Getting-started.dr. |       └── avails/ │            └── images/ │                 ├── architecture/ │                 │     └── hallmark-diagram.png │                 ├── infrastructure/ |                 |     └── heroku-dyno.png |                 └── operations/ |                       └── data-consign.png ...

To keep things organized, replicate the content structure of the markdown files inside the images directory besides.

Nosotros can then link images inside the content using a relative URL.

Calculation images normally:

                                          ![                      Heroku Dyno Overview                      ](                      assets/images/infrastructure/heroku-dyno.png                      )

Adding with a set width/summit:

                    [[assets/images/infrastructure/heroku-dyno.png|alt="Heroku Dyno Overview"|height=210px|width=210px]]

Use SVG image format wherever possible as they calibration well and are easier to see in large infrastructure/architecture diagrams. Lucid nautical chart supports exporting in SVGs. 📈

Referencing Internal Pages

Use one of the post-obit syntaxes to link to other pages within the wiki. There is no need for the absolute path.

For case: given a file name Automated-code-review.medico, it can exist linked to as:

                [[Automated code review]]

We tin likewise use a dissimilar title for the link.

For example: given a file name Scale-in-out-manually.dr., a link can be created with a freely chosen championship to refer to that folio as:

                [[Calibration ECS cluster in/out manually|Calibration in out manually]]

The default sidebar of Github is a apartment list of all pages in alphabetical order. We recommend using a custom sidebar to add together a visual hierarchy to documentation for easier reference.

Use the headings in our documentation organization in the _Sidebar.md. When calculation a new page, exist sure to link the page equally a link in the Sidebar under the right department.

A typical sidebar follows our organisation structure as follows:

                          ## Tabular array of Contents                              -              [[Domicile]]              -              [[Getting Started]]              ## Architecture                              -              [[Authentication Menstruum]]              -              [[Assistants]] ...              ## Infrastructure                              -              [[Cron Jobs]]              -              [[Deployment Procedure]]              -              [[Environment Variables]] ...              ## Operations                              -              [[Debugging]]              -              [[Testing]] ...

moonseir1950.blogspot.com

Source: https://nimblehq.co/compass/development/documentation/github-wiki/