Skip to main content

Example README

Last updated on

Welcome to the SCOOBY customer documentation repository!

This repo is the source for https://scooby-docs-next.vercel.apps/, also known as "The Docs"! The SCOOBY documentation is completely open-source and we appreciate contributions from the community.

Provide feedback​

Your feedback is essential in shaping the customer content experience. There are several ways to provide feedback:

The Product team will track these ideas and issues to address your feedback.

Request improvements​

You can request the documentation to be improved or clarified, report an error, or submit suggestions and ideas by opening an issue in GitHub. The Product team tracks the issues and works to address your feedback.

Contribute to the docs​

Refer to the contributor's guide for details on how to submit edits or additions to the website/documentation.

Doc branches​

Before you get started with the authoring work, it's necessary that you understand the different branches to work on.

  • main - protected branch

    Docs for https://scooby-docs-next.vercel.app. This branch contains the most recent stable release content.

  • docs-staging - protected branch

    Docs for the upcoming vNext release. When SCOOBY has a release, its docs-staging branch will be merged into main.

  • active-development - protected branch

    Docs for a forward-version that includes features not yet included in the SCOOBY stable version. Its content is published on https://scooby-docs-next.vercel.app/active-development for early validation purpose.

  • v<v.r>.x - protected branches

    Docs for an archived version, where v indicates the version, r indicates the release number. For example, v1.0.x, v1.1.x, v1.6.x.

  • Branches that start with release- contain archived patch release documentation for historical tracking.

  • You can have your own personal branch to work on content for a certain issue or feature. However, be sure to check and remove unused personal branches periodically for easy maintenance. Usually when your branch is merged, you can safely delete it.

Site organization and files​

  • /docs/ - Contains the Markdown files for the docs. Customize the order of the docs sidebar in sidebars.js.
  • /docusaurus.config.js - A config file containing the site configuration.
  • /sidebar.js - Specify the order of documents in the sidebar. If you have a new file to add to the site, modify this file.
  • /src/ - Non-documentation files like pages or custom React components.
    • /src/pages - Any files within this directory will be converted into a website page.
  • /static/ - Static directory. Any contents inside here will be copied into the root of the final build directory.
  • /package.json - A Docusaurus website is a React app. You can install and use any npm packages you like in them.

Run the doc site locally​

Prerequisites​

Clone the repo​

  1. Clone the repo. This creates a directory named scooby-docs-next in your current working directory.

    git clone https://github.com/goscooby/scooby-docs-next.git
    cd scooby-docs-next

  2. Next, create a new branch from main (always give your branch a meaningful, descriptive name). 

    git checkout -b <branch_name> main

Start the development server​

We're finally able to get to the fun stuff! Install the dependencies and start a local development server:

yarn
yarn start

The http://localhost:3000 opens in your browser so you can see your changes reflected live.As you make changes to the source files, the preview build will be triggered automatically, and then you can refresh your browser to see the changes.

Thank you!​

We appreciate your contributions to our documentation!

Interested in enhancing your project with user-centric technical writing and content design?

Let's talk.

Helpful links.