DEVELOPMENT.md

Appsody.dev Development

The Appsody website is built with Gatsby.js. See the Gatsby quick start guide for the basics.

Prerequisites

• Node 10+ Download Node.js from https://nodejs.org/en/

• Gatsby.js When Node is installed, run the following command to install Gatsby.js:

    npm install -g gatsby-cli

• Install Node dependencies Clone the website Git repo and install the dependencies with the following commands:

    git clone https://github.com/appsody/website.git
    cd website
  
    npm install

Developing locally

1. Run the development server:

gatsby develop

This command compiles your changes as you develop and hosts the website at http://localhost:8000. To explore GraphQL queries that Gatsby exposes, use http://localhost:8000/__graphql.

📝 Note about clearing your Cache: Sometimes when developing locally, the website shows cached content from previous versions of the website. To clear the cache before developing, run the following command:

gatsby clean

2. View documentation at http://localhost:8000/docs

For more information on adding Markdown pages with Gatsby, see https://www.gatsbyjs.org/docs/adding-markdown-pages/

To manually test links within your documentation, follow the instructions for Testing the website ready for release.

📝 Note: If you are developing remotely, use http://<hostname>:PORT instead of http://localhost:PORT as described in this doc.

Contributing Documentation

We welcome contributions to the Appsody documentation.

Understanding the documentation structure

Documentation for Appsody must be stored in the content/docs directory. Images must be stored in the content/docs/images directory.

The documentation should follow the rough structure of the sidebar so that the docs are easy to find. The getting started guide, for example, is located in content/docs/getting-started.

At the top of each documentation page you should include frontmatter so that the website can render the page correctly. Include the following elements:

---
path: This is the route to the page that all links will be created from.
---

For example:

---
path: /docs/getting-started/quick-start
---

To add the doc to the side menu you must add it to the sidebar.yaml in content/docs. A section is defined using the following structure:

- title (optional): Getting Started
  items:
    - title: Installation
      path: /docs/getting-started/installation
    - title: Quick Start
      path: /docs/getting-started/quick-start

📝 Note: The title for the section is optional but the title for each menu item is required.

Using images

Images can help explain concepts better than words, and make for more exciting and digestible content.

First, copy the image file to the content/docs/images directory.

To add an inline image to a doc, use the following syntax:

![Alt Text](../images/my-awesome-image.png)

A helpful image could show a window that a user is expected to see. Make sure you replace [Alt Text] with some text describing what the image shows, as this text is used for screen readers, or for when the image does not load.

Note: Relative paths must be used to reference image locations. If an image does not render properly, you might be pointing to the wrong directory. Use only images of file type .png or .jpg.

Writing technical content

Writing good technical content that is easy to read and understand is important for the success of any product. For consistency across the documentation, these guidelines should be followed:

1. Use an active voice:

   ❎ NO: When the file is opened, the entry xxx can be deleted.

   ✅ YES: Open the file and delete entry xxx.

2. Use present tense:

   ❎ NO: The command will create a new directory...

   ✅ YES: The command creates a new directory...

3. Use the first person to engage the audience:

   ❎ NO: The user has two options....

   ✅ YES: You have two options...

4. Be aware of words that convey position.

   ❎ NO: Run the command shown below:

   ✅ YES: Run the following command:

   📝 NOTE: Words such as above, below, left, right, top, and bottom break accessibility guidelines when used in isolation.

5. Avoid ambiguity:

   ❎ NO: This causes a problem with... (what is this referring to?)

   ✅ YES: This behavior causes a problem with...

And finally, to help users for whom their first language is not English:

• use simple language
• keep sentences short
• avoid needless words

Redirecting content

If you move a document from one location to another you must add a redirect to prevent broken links, especially from external sources.

1. Open the gatsby-node.js file found at the root of the project
2. In the redirects section, add the following code snippet:

createRedirect({
    fromPath: `/old/path`,
    toPath: `/new/path`,
    isPermanent: true
  });

Note, you need to provide only the path.

3. Add a comment above the redirect stating why it was added.

Adding definitions to the Glossary page

If you feel a term would benefit from being defined, the Glossary is the perfect place to do so! The file is located inside the docs directory, as glossary.md.

In order to render correctly, definitions need to be written in the following way:

>### Term Name
This is where you would write a brief description explaining the term.
Feel free to include links, images, and inline code snippets. Code blocks are supported.

For a new line, end the sentence with two spaces before pressing the enter key.

For an empty line, insert an empty character ( ) with two spaces following it.

The large letters, marking the letter of the alphabet the definitions belong to, are simply written with the following syntax:

## Letter

The glossary is not self-organising, so try to add definitions in their correct place alphabetically.

Testing the website ready for release

Before submitting a pull request you must test that the website can build and run successfully.

1. Build the website

gatsby build

This build must be successful or you cannot serve the website.

2. Serve the website

gatsby serve

3. Access the website on http://localhost:9000 and complete any visual checks.

Adding a tutorial

Tutorials can help a user understand a concept or work to acheive a goal. Tutorials are written in Markdown format, similarly to docs and blogs. The files need to be added to content/tutorials/.

Make sure all code blocks are enclosed using the triple backtick notation.

Images need to be placed in the resources folder which is located inside the tutorials folder. For further information see Using images

Tutorials also require a small amount of frontmatter, to let the site know some extra information such as title, appoximate length, author etc. Below is an example of the required information:

---
title: "Title of the Tutorial here"
date: "2020-03-18"
author: "Joe Bloggs"
tutorial: "true"
length: "1 hour 30 mins"
---

Code blocks need to have their respective backticks on their own lines, so make sure you use 3 backticks, then a new line, then the code with a new line at the end, followed by the closing 3 backticks on their own line too.

When you estimate the length of time that is required to complete the tutorial, consider who the tutorial is aimed at. If it’s an advanced guide, expect someone with more experience in the subject matter to be using the tutorial. For more basic tutorials, a new developer might follow along at a slower pace.

Adding a blog

Appsody blogs must be stored in the content/blogs directory. Images that are used in the blogs must be stored in the content/docs/resources directory.

Blogs must be written in Markdown. At the top of each blog page, you need to include the following frontmatter so that the website can render the page correctly. Include the following elements:

---
title: "Title of the blog"
date: "Date the blog is published"
author: "Name of the author"
---

📝 Note: The title, date and author are required for each blog. The date format needs to be yyyy-mm-dd.

For other formatting queries, follow the format of the existing blog listings, or talk to the community on Slack.

Blogs are rendered on the blogs page in date order, from most recent to oldest.

Need help?

If you have a question that you can't find an answer to, we want to hear from you. Reach out to the community for assistance on Slack.