Skip to content
Open
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 8 additions & 6 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
# Description

_Please include a summary of the change and which issue is fixed. Please also include relevant
motivation and context. List any dependencies that are required for this change._
_Please include a summary of the change and which issue is fixed. Please also
include relevant motivation and context. List any dependencies that are required
for this change._

Fixes # (issue)

Expand All @@ -11,14 +12,15 @@ _Please delete options that are not relevant._

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as
expected)
- [ ] Breaking change (fix or feature that would cause existing functionality to
not work as expected)
- [ ] Documentation (update or new)

## How Has This Been Tested?

_Please describe the tests that you ran to verify your changes. Provide instructions so we can
reproduce. Please also list any relevant details for your test configuration_
_Please describe the tests that you ran to verify your changes. Provide
instructions so we can reproduce. Please also list any relevant details for your
test configuration_

## Testing Checklist

Expand Down
1 change: 0 additions & 1 deletion .prettierrc
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
{
"printWidth": 100,
"proseWrap": "always"
}
104 changes: 57 additions & 47 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,40 +1,42 @@
# Contributing

You can help to improve the Thoth Tech documentation by sending pull requests to this repository.
Thank you for your interest and help!
You can help to improve the Thoth Tech documentation by sending pull requests to
this repository. Thank you for your interest and help!

Feel free to make a proposal, we can discuss anything and if we don't agree we'll feel free not to
merge it and we'll thank you for caring about it. We want to create a welcoming environment for
everyone who is interested in contributing.
Feel free to make a proposal, we can discuss anything and if we don't agree
we'll feel free not to merge it and we'll thank you for caring about it. We want
to create a welcoming environment for everyone who is interested in
contributing.

## Documentation testing

We treat documentation like code. Therefore, we use processes similar to those used for code to
maintain standards and quality of documentation.
We treat documentation like code. Therefore, we use processes similar to those
used for code to maintain standards and quality of documentation.

We have tests:

- To lint the words and structure of the documentation.

### Run tests locally

You can run these tests on your local computer. This has the advantage of speeding up the feedback
loop. You can know of any problems with the changes in your branch without waiting for a CI pipeline
to run.
You can run these tests on your local computer. This has the advantage of
speeding up the feedback loop. You can know of any problems with the changes in
your branch without waiting for a CI pipeline to run.

To run the tests locally, it's important to:

- [Install the tools](#installation)
- Run [linters](#lint-checks) the same way they are run in CI pipelines. It's important to use same
configuration we use in CI pipelines, which can be different than the default configuration of the
tool.
- Run [linters](#lint-checks) the same way they are run in CI pipelines. It's
important to use same configuration we use in CI pipelines, which can be
different than the default configuration of the tool.

### Local linters

To help adhere to the
[documentation style guidelines](https://github.com/thoth-tech/handbook/blob/main/docs/processes/documentation/writing-style-guide.md),
and improve the content added to documentation, [install documentation linters](#install-linters)
and [integrate them with your code editor](#configure-editors).
and improve the content added to documentation,
[install documentation linters](#install-linters) and
[integrate them with your code editor](#configure-editors).

At Thoth Tech, we mostly use:

Expand All @@ -48,13 +50,14 @@ At Thoth Tech, we mostly use:

#### Vale

[Vale](https://docs.errata.ai/vale/about/) is a grammar, style, and word usage linter for the
English language. Vale's configuration is stored in the
[`.vale.ini`](https://github.com/thoth-tech/documentation/blob/main/.vale.ini) file located in the
root directory.
[Vale](https://docs.errata.ai/vale/about/) is a grammar, style, and word usage
linter for the English language. Vale's configuration is stored in the
[`.vale.ini`](https://github.com/thoth-tech/documentation/blob/main/.vale.ini)
file located in the root directory.

Vale supports creating [custom tests](https://docs.errata.ai/vale/styles) that extend any of several
types of checks, which we store in the `.vale/thothtech/` directory in the documentation directory.
Vale supports creating [custom tests](https://docs.errata.ai/vale/styles) that
extend any of several types of checks, which we store in the `.vale/thothtech/`
directory in the documentation directory.

##### Vale result types

Expand All @@ -72,13 +75,14 @@ we have implemented
[the Flesch-Kincaid grade level test](https://readable.com/readability/flesch-reading-ease-flesch-kincaid-grade-level/)
to determine the readability of our documentation.

As a general guideline, the lower the score, the more readable the documentation. For example, a
page that scores `12` before a set of changes, and `9` after, indicates an iterative improvement to
readability. The score is not an exact science, but is meant to help indicate the general complexity
level of the page.
As a general guideline, the lower the score, the more readable the
documentation. For example, a page that scores `12` before a set of changes, and
`9` after, indicates an iterative improvement to readability. The score is not
an exact science, but is meant to help indicate the general complexity level of
the page.

The readability score is calculated based on the number of words per sentence, and the number of
syllables per word. For more information, see
The readability score is calculated based on the number of words per sentence,
and the number of syllables per word. For more information, see
[the Vale documentation](https://docs.errata.ai/vale/styles#metric).

#### Installation
Expand All @@ -87,20 +91,21 @@ syllables per word. For more information, see

##### macOS

1. Install [Homebrew](https://brew.sh/), which is a package manager for macOS that allows you to
easily install programs and tools through the Terminal. Visit their website for installation
instructions.
1. Install [Homebrew](https://brew.sh/), which is a package manager for macOS
that allows you to easily install programs and tools through the Terminal.
Visit their website for installation instructions.
1. Follow the
[official instructions to install nvm](https://github.com/nvm-sh/nvm#installing-and-updating), a
Node version manager. Then, run the following to install and use the repository's Node version:
[official instructions to install nvm](https://github.com/nvm-sh/nvm#installing-and-updating),
a Node version manager. Then, run the following to install and use the
repository's Node version:

```shell
nvm install
nvm use
```

The required Node version should be automatically detected from the `.nvmrc` file. This can be
confirmed by running `nvm which`.
The required Node version should be automatically detected from the `.nvmrc`
file. This can be confirmed by running `nvm which`.

1. Install all dependencies

Expand All @@ -110,9 +115,10 @@ syllables per word. For more information, see

##### Windows (using WSL2)

1. Set up Windows Subsystem for Linux (WSL) and the Linux distribution. WSL allows Linux
distributions to run on the Windows OS. Visit this
[website](https://docs.microsoft.com/en-us/windows/wsl/install) for more information.
1. Set up Windows Subsystem for Linux (WSL) and the Linux distribution. WSL
allows Linux distributions to run on the Windows OS. Visit this
[website](https://docs.microsoft.com/en-us/windows/wsl/install) for more
information.

```powershell
wsl --install
Expand All @@ -129,16 +135,17 @@ syllables per word. For more information, see
```

1. Follow the
[official instructions to install nvm](https://github.com/nvm-sh/nvm#installing-and-updating), a
Node version manager. Then, run the following to install and use the repository's Node version:
[official instructions to install nvm](https://github.com/nvm-sh/nvm#installing-and-updating),
a Node version manager. Then, run the following to install and use the
repository's Node version:

```shell
nvm install
nvm use
```

The required Node version should be automatically detected from the `.nvmrc` file. This can be
confirmed by running `nvm which`.
The required Node version should be automatically detected from the `.nvmrc`
file. This can be confirmed by running `nvm which`.

1. Install all dependencies

Expand All @@ -163,10 +170,11 @@ These tools can be [integrated with your code editor](#configure-editors).

### Configure editors

Using linters in your editor is more convenient than having to run the commands from the command
line.
Using linters in your editor is more convenient than having to run the commands
from the command line.

To configure `prettier` in your editor, install one of the following as appropriate:
To configure `prettier` in your editor, install one of the following as
appropriate:

- Visual Studio Code
[`esbenp.prettier-vscode` extension](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode).
Expand All @@ -178,7 +186,8 @@ To configure Vale in your editor, install one of the following as appropriate:

### Lint checks

The following commands can be run to format all Markdown files across the entire repository:
The following commands can be run to format all Markdown files across the entire
repository:

```shell
# Format markdown style (fixing markdown style issues)
Expand All @@ -196,5 +205,6 @@ npm run prose:check

## Contributing guidelines

Contributing formatting guidelines, including git workflow and commit formatting requirements can be
found in our [git contribution guide](docs/processes/quality-assurance/git-contribution-guide.md).
Contributing formatting guidelines, including git workflow and commit formatting
requirements can be found in our
[git contribution guide](docs/processes/quality-assurance/git-contribution-guide.md).
66 changes: 37 additions & 29 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,28 +11,32 @@
[![Forks](https://img.shields.io/github/forks/thoth-tech/ThothTech-Documentation-Website?label=Forks&color=F5A623)](https://github.com/thoth-tech/ThothTech-Documentation-Website/network/members)
[![Stars](https://img.shields.io/github/stars/thoth-tech/ThothTech-Documentation-Website?label=Stars&color=F5A623)](https://github.com/thoth-tech/ThothTech-Documentation-Website/stargazers)

Welcome to the **ThothTech Documentation Website** repository! This project serves as the central
hub for all Thoth Tech resources, designed to provide a structured and accessible platform for
documentation, product information, and team resources. This contains out long term documentation,
such as the documentation for onboarding information, general information and company deliverables.

Short term documentation such as spike reports and sprint reports are stored in the
[Documentation](https://github.com/thoth-tech/documentation) repository.

Built with Astro and Starlight, this website offers an organized space where users can explore Thoth
Tech's mission, values, and goals, along with in-depth information on each of the company's products
and services. Each product has its own dedicated section, featuring a brief overview, its purpose,
and comprehensive documentation to support both users and development teams.

The site also includes team documentation for each semester, highlighting the efforts of the
individuals contributing to Thoth Tech's ongoing projects. Whether you're a developer, a team
member, or a user, this website provides all the information needed to understand and contribute to
Thoth Tech's vision and initiatives.
Welcome to the **ThothTech Documentation Website** repository! This project
serves as the central hub for all Thoth Tech resources, designed to provide a
structured and accessible platform for documentation, product information, and
team resources. This contains out long term documentation, such as the
documentation for onboarding information, general information and company
deliverables.

Short term documentation such as spike reports and sprint reports are stored in
the [Documentation](https://github.com/thoth-tech/documentation) repository.

Built with Astro and Starlight, this website offers an organized space where
users can explore Thoth Tech's mission, values, and goals, along with in-depth
information on each of the company's products and services. Each product has its
own dedicated section, featuring a brief overview, its purpose, and
comprehensive documentation to support both users and development teams.

The site also includes team documentation for each semester, highlighting the
efforts of the individuals contributing to Thoth Tech's ongoing projects.
Whether you're a developer, a team member, or a user, this website provides all
the information needed to understand and contribute to Thoth Tech's vision and
initiatives.

## Format Checks to Run

To maintain code quality, please ensure you run the following commands before submitting a pull
request:
To maintain code quality, please ensure you run the following commands before
submitting a pull request:

1. **Format the Files**:

Expand All @@ -54,8 +58,8 @@ request:

## Project Structure

This website is built with Astro and uses the **Starlight Starter Kit** as a foundation. Below is a
breakdown of the project structure:
This website is built with Astro and uses the **Starlight Starter Kit** as a
foundation. Below is a breakdown of the project structure:

```plaintext
.
Expand All @@ -71,9 +75,10 @@ breakdown of the project structure:
└── tsconfig.json # TypeScript configuration
```

- **Documentation Content**: `.md` or `.mdx` files placed in `src/content/docs/` are exposed as
routes based on their filenames.
- **Static Assets**: Place images and other static files in `public/` for easy access.
- **Documentation Content**: `.md` or `.mdx` files placed in `src/content/docs/`
are exposed as routes based on their filenames.
- **Static Assets**: Place images and other static files in `public/` for easy
access.

## Commands

Expand All @@ -92,7 +97,8 @@ All commands should be run from the root of the project in the terminal:

## Getting Started

To initialize the project, use the following Astro command to set up with the Starlight Starter Kit:
To initialize the project, use the following Astro command to set up with the
Starlight Starter Kit:

```shell
npm create astro@latest -- --template starlight
Expand All @@ -104,7 +110,9 @@ For more information, check out the [CONTRIBUTING.md](CONTRIBUTING.md) file.

For additional resources, check out the following:

- **[Starlight Documentation](https://starlight.astro.build/)**: Learn more about the Starlight
Starter Kit.
- **[Astro Documentation](https://docs.astro.build)**: Understand the Astro framework.
- **[Astro Discord Server](https://astro.build/chat)**: Connect with the Astro community.
- **[Starlight Documentation](https://starlight.astro.build/)**: Learn more
about the Starlight Starter Kit.
- **[Astro Documentation](https://docs.astro.build)**: Understand the Astro
framework.
- **[Astro Discord Server](https://astro.build/chat)**: Connect with the Astro
community.
33 changes: 19 additions & 14 deletions src/content/docs/Feedback/feedback-form.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,37 +5,42 @@ description: A way to provide feedback

# We Value Your Feedback

Thank you for taking the time to share your thoughts with us. Your feedback is crucial for helping
us improve and ensuring we continue to provide the best possible experience.
Thank you for taking the time to share your thoughts with us. Your feedback is
crucial for helping us improve and ensuring we continue to provide the best
possible experience.

## How to Provide Feedback

You have several convenient options for submitting your feedback. Please choose the one that best
suits your preference:
You have several convenient options for submitting your feedback. Please choose
the one that best suits your preference:

### Option 1: Fill Out Our Online Form

Open an issue in our
[GitHub repository](https://github.com/thoth-tech/ThothTech-Documentation-Website/issues). It only
takes a few minutes and helps us understand your perspective.
[GitHub repository](https://github.com/thoth-tech/ThothTech-Documentation-Website/issues).
It only takes a few minutes and helps us understand your perspective.

### Option 2: Contact Your Team Leader or Senior Students

For specific feedback or concerns that require direct communication, please reach out to your team
leader or senior students. This ensures your feedback is addressed promptly and personally.
For specific feedback or concerns that require direct communication, please
reach out to your team leader or senior students. This ensures your feedback is
addressed promptly and personally.

---

## What Happens Next?

Once you submit your feedback:

- **Review:** Our team will review your feedback to understand your needs and concerns.
- **Plan:** We will plan improvements based on the feedback received from you and other users.
- **Implement:** We will strive to implement changes and improvements continuously to enhance your
experience.
- **Review:** Our team will review your feedback to understand your needs and
concerns.
- **Plan:** We will plan improvements based on the feedback received from you
and other users.
- **Implement:** We will strive to implement changes and improvements
continuously to enhance your experience.

Your input is incredibly valuable to us, and we appreciate the effort you put into helping us
improve. If you have any immediate concerns, please contact our company operations team.
Your input is incredibly valuable to us, and we appreciate the effort you put
into helping us improve. If you have any immediate concerns, please contact our
company operations team.

Thank you for your contribution!
Loading
Loading