Skip to content

Latest commit

 

History

History
161 lines (102 loc) · 5.28 KB

DEVELOPMENT.md

File metadata and controls

161 lines (102 loc) · 5.28 KB
Raw

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
  1. 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/

📝 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 quick start guide, for example, is located in content/docs/getting-started/quick-start.

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

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.

  1. Serve the website
gatsby serve
  1. Access the website on http://localhost:9000 and complete any visual checks.

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.