Skip to content

Commit

Permalink
No commit message
Browse files Browse the repository at this point in the history
  • Loading branch information
NikolaRHristov committed Oct 9, 2024
2 parents a1c6561 + ed48763 commit 9353db3
Show file tree
Hide file tree
Showing 385 changed files with 52,315 additions and 138 deletions.
5 changes: 5 additions & 0 deletions .github/CODEOWNERS
Validating CODEOWNERS rules …
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# Order is important; the last matching pattern takes the most precedence.
* @tauri-apps/wg-doc

# Disabled until wg-devops has active members
# .github @tauri-apps/wg-devops
113 changes: 113 additions & 0 deletions .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,113 @@
# Contributing

Welcome to Tauri Docs! We're excited to have you 🥳

[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/tauri-apps/tauri-docs/tree/v2)
[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/tauri-apps/tauri-docs/tree/v2)

There are a number of ways to get involved:

- See if there are any [good first issues](https://github.com/tauri-apps/tauri-docs/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) that catch your eye
- [Write a guide or recipe](#write-documentation)
- [Translating existing documentation](#translations-i18n)

Reach out to us on [Discord](https://discord.com/invite/tauri) on the [`#docs` channel](https://discord.com/channels/616186924390023171/662624589037436928) if you have any questions!

## Getting Started

1. Clone this repo
2. Run `pnpm i && pnpm dev:setup`
3. Run `pnpm dev` to start the local server

### Gitpod

[Allow Gitpod to open new tabs](https://www.gitpod.io/docs/configure/user-settings/browser-settings) so you immediately when the environment is done loading get a new tab popping up with the documentation.

## Write Documentation

We have the following types of documents that roughly follow the types defined by [Diátaxis](https://diataxis.fr/):

- **[Guide](#guide)**: Learning-oriented
- **[Recipe](#recipe)**: Task-oriented
- **[Reference](#recipe)**: Information-oriented
- **[Blog Post](#blog-post)**: Understanding-oriented

Use this chart to help you figure out where the right place for your content is:

| If the content describes… | …and serves the user's… | …then it must belong to… |
| ------------------------- | ----------------------- | ------------------------- |
| practical steps | study | [a guide](#guide) |
| practical steps | work | [a recipe](#recipe) |
| theoretical knowledge | work | [a reference](#reference) |
| theoretical knowledge | study | [a blog post](#blog-post) |

### Writing for Prerelease

While Tauri 2.0 is still in the prerelease stage people follow these guidelines for writing documentation:

- Refer to Tauri 2.0 as if it's released now (so that copy doesn't need to be updated upon release)
- Write any code so that it works **now** but...
- Annotate 2.0 code with `{/* FIXME: 2.0 */}` (.mdx files) or `<!-- FIXME: 2.0 -->` (.md files) so that we can easily find and fix any of those upon release (feel free to add in what the code should be upon release in additional comments)

### Writing Style

**Dictionary**

| Word | Description |
| -------- | ------------------------------------ |
| app | A Tauri app, prefer over application |
| web view | Where the UI is rendered |

- Use an [oxford comma](https://www.grammarly.com/blog/what-is-the-oxford-comma-and-why-do-people-care-so-much-about-it/) in paragraphs, but not in headings and titles
- Use [title case](https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case) for headings and titles
- Make headings as succinct as possible to help the reader quickly find the content they need
- Use [simple present tense](https://www.grammarly.com/blog/simple-present/) for verbs

### Guide

Located in [`/src/content/docs/2/guide/`](https://github.com/tauri-apps/tauri-docs/tree/starlight/src/content/docs/2/guide)

Guides are learning-oriented and take the reader through a specific journey such as starting a new project, and overview of a specific feature, or how to follow a specific flow such as building and bundling their app. They follow a similar philosophy to [tutorials in Diátaxis](https://diataxis.fr/tutorials).

The reader should be familiar with the concepts covered by the end of the guide and should set them up with the knowledge required to being experimenting with that topic themselves.

### Recipe

Located in [`/src/content/docs/2/recipe/`](https://github.com/tauri-apps/tauri-docs/tree/starlight/src/content/docs/2/recipe)

Recipes are designed to guide the reader through a specific task similar and have a clear outcome and objective. This could be something like setting up authentication using Firebase, adding a Python binary using sidecar, or requesting admin access on a user's machine. They are similar to [how-to guides in Diátaxis](https://diataxis.fr/how-to-guides) (not to be confused with our own guides mentioned above).

The prerequisites for a recipe should be clearly stated. If there are a lot of steps required before getting into the relevant information about the recipe then you may want to link out to another guide, recipe, or external resource and state those as a prerequisite at the top of the recipe.

### Reference

Located in [`/src/content/docs/2/reference/`](https://github.com/tauri-apps/tauri-docs/tree/starlight/src/content/docs/2/reference), although they should be auto-generated when possible.

References are where all the nuts and bolts of Tauri's API are documented. These should be generated from upstream repos when possible and written following the best practices described by [references in Diátaxix](https://diataxis.fr/reference).

These should be as succinct and to the point as possible so that the reader can quickly find the relevant information.

If you'd like to view the API references locally then you must run `pnpm dev:setup` before `pnpm dev` to initialize all of the submodules. Now the `http://localhost:3000/2/reference/` routes are available to preview.

### Blog Post

Not yet created, will be added in the future.

Topics that are around understanding something can be written as a blog post (we welcome submissions to the Tauri blog from anyone). Blog posts are a good option because they help the reader understand that information is accurate at the time of writing (and of course can always be updated later if it becomes stale). Blog posts follow the goals of [explanation in Diátaxis](https://diataxis.fr/explanation), but not all blog posts necessarily fit this specific format.

### Diagrams

We use [Astro D2](https://astro-d2.vercel.app/) to generate diagrams. Because Netlify does not support compiling the diagrams in its end we have to push the prebuilt images manually. This is annoying, but not the end of the world seeing as we've previously been pushing the images manually anyway.

If you make an update to a diagram you'll need to [install D2](https://github.com/terrastruct/d2/blob/master/docs/INSTALL.md) on your system, then when you run either the `build` or `dev` commands you'll need to enable building the diagrams by setting the environment variable `CONTEXT=d2`.

```sh
# Adapt the command as relevant for your system to define the variable
CONTEXT=d2 pnpm dev
```

## Translations (i18n)

Thanks for your interest in helping to translate the documentation! Visit the [translation status page](https://v2.tauri.app/contribute/translate-status) to see which docs are ready for translation, need updated, or need reviewed.

Read the [Translating Guide](./TRANSLATING.md) for more information.
9 changes: 9 additions & 0 deletions .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# Copyright 2019-2024 Tauri Programme within The Commons Conservancy
# SPDX-License-Identifier: Apache-2.0
# SPDX-License-Identifier: MIT

blank_issues_enabled: true
contact_links:
- name: 💬 Discord Chat
url: https://discord.com/invite/tauri
about: Ask questions and talk to other Tauri users and the maintainers
50 changes: 50 additions & 0 deletions .github/ISSUE_TEMPLATE/page_request.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
# Copyright 2019-2024 Tauri Programme within The Commons Conservancy
# SPDX-License-Identifier: Apache-2.0
# SPDX-License-Identifier: MIT

name: 🤔 v2 Page Request
title: '[request] '
description: Request a new page or updated content
labels:
- enhancement
- discuss

body:
- type: input
id: question
attributes:
label: Question you want answered
description: The question you were trying to get answered by going to the website and couldn't find. Even if you weren't looking to get a specific question answered try to encapsulate the essence of your issue in the form of a question.
placeholder: "How do I register a new State?"
validations:
required: true

- type: textarea
id: answer
attributes:
label: Where did you look for an answer?
description: Think back on how you navigate the site in order to find the answer to your question so we get a better idea of how people interact with the site.
placeholder: First I tried searching for the issue, then I went to the sidebar to find a relevant page...
validations:
required: true

- type: input
id: url
attributes:
label: Page URL
description: If applicable, copy-paste the URL to the page you want updated.
placeholder: "https://v2.tauri.app/some/specific/page"

- type: textarea
id: context
attributes:
label: Additional context
description: Add any other context about the problem here.

- type: checkboxes
attributes:
label: Are you willing to work on this yourself?
description: If so don't hesitate to reach out on Discord to us, we're more than happy to help you get set up with contributing!
options:
- label: I want to work on this myself
required: false
23 changes: 23 additions & 0 deletions .github/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
<!-- Thank you for opening a PR! We really appreciate you taking the time to help out 🙌 -->

#### Description
<!-- Translators, try to follow this pattern when naming your PRs:
"i18n(language code): (short description)" -->
- What does this PR change? Give us a brief description. <!-- If it's an update try adding the commits as reference -->
- Closes # <!-- Add an issue number if this PR will close it or remove it. -->

<!--
Here's what will happen next:
1. Our GitHub bots will run to check your changes.
If they spot any broken links you will see some error messages on this PR.
Don't hesitate to ask any questions if you're not sure what these mean!
2. In a few minutes, you'll be able to see a preview of your changes on Netlify 🥳
3. One or more of our maintainers will take a look and may ask you to make changes.
We try to be responsive, but don't worry if this takes a day or two.
4. Reach out to us on Discord with any questions along the way:
https://discord.com/invite/tauri
-->
88 changes: 88 additions & 0 deletions .github/TRANSLATING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
# Translations (i18n)

Thanks for your interest in helping translate the Tauri docs! Visit the [translation status page](https://v2.tauri.app/contribute/translate-status) to see which docs are ready for translation, need updated, or need reviewed.

To ensure a translation is consistent across multiple contributions, be sure to [communicate with others contributors in the `#docs` channel on Discord](https://discord.com/invite/tauri) and consult with reliable external resources such as [Microsoft terminology search](https://msit.powerbi.com/view?r=eyJrIjoiODJmYjU4Y2YtM2M0ZC00YzYxLWE1YTktNzFjYmYxNTAxNjQ0IiwidCI6IjcyZjk4OGJmLTg2ZjEtNDFhZi05MWFiLTJkN2NkMDExZGI0NyIsImMiOjV9) during translation.

## Enabling a Language

If you seek to contribute but find your language missing please let us know in https://github.com/tauri-apps/tauri-docs/issues/1611. Once we have enough support for a particular language then we'll be able to enable it with the community's support.

### Maintainer Checklist for Adding New Languages

- Update https://github.com/tauri-apps/tauri-docs/blob/v2/locales.json
- Update https://github.com/tauri-apps/tauri-docs/blob/v2/.github/labeler.yml

## Starting a Translation

Before you start working on a translation, look through the [open pull requests](https://v2.tauri.app/contribute/translate-status#needs-review) to see if anyone else is already working on the page for that language.

If that page isn't in the list, then now it's time for you to lead the effort! So here's how to start:

1. Head to [translation status page](https://v2.tauri.app/contribute/translate-status).
2. Look for missing translation in corresponding languages.
3. Make sure no one else has been working on the corresponding page.
4. Click `Create page +` which will help you automagically fork the repository and create the corresponding page. You might want to copy the contents of English page as a starting point.
5. Translate the page following the [translation guidelines](#translation-guidelines).
6. Once your translation is done, initiate a pull request.

Note that you may submit a draft pull request before your translation is complete: e.g., you may want to ask for help with translations or simply indicate to others that you're already translating a specific page. However, your pull request will not be merged until the translation is complete.

## Updating a Translation

### Corrections

If you notice spelling or grammar errors, typos, or opportunities for better phrasing, open a pull request with your suggested fix. If you see a problem that you aren't sure of or don't have time to fix, open an issue.

### Broken Links

When broken links are found, try to fix them across all translations. Ideally, only update the linked URLs, so that translation review will not be necessary.

## Translation Guidelines

Here are some guidelines to help with the translation.

**Markdown Formatting**

- [ ] Preserve the Markdown formatting. This includes headers (#, ##, etc.), lists (*, -, 1.), and inline styles like bold, italic, and code.
- [ ] Ensure that links ([link text](URL)) remain functional and direct to the correct locations.
- [ ] Ensure code blocks (triple backticks ```) are unchanged in terms of their syntax and content.
- [ ] Double-check tables, making sure their structure remains intact. Using the Prettier formatter is a great way to do this.

**Terminology**

- [ ] Familiarize yourself with key Tauri terms and ensure they're translated consistently. It may be helpful to look at other, already translated pages as a reference.
- [ ] For some terms, it might be appropriate to keep them in English and provide a translation in parentheses.
- [ ] If a term has no definitive way to translate, be sure to [communicate with others contributors in the `#docs` channel on Discord](https://discord.com/invite/tauri) or through pull request and consult with reliable external resources such as [Microsoft terminology search](https://msit.powerbi.com/view?r=eyJrIjoiODJmYjU4Y2YtM2M0ZC00YzYxLWE1YTktNzFjYmYxNTAxNjQ0IiwidCI6IjcyZjk4OGJmLTg2ZjEtNDFhZi05MWFiLTJkN2NkMDExZGI0NyIsImMiOjV9).

**Code and Command Examples**

- [ ] Avoid translating code unless it contains explanatory comments. Translated comments should retain the original meaning.
- [ ] Ensure command-line examples remain functional. Only translate the descriptive parts, not the actual commands.

**Link Descriptions**

- [ ] If link descriptions (text that appears when you hover over a link) are present, make sure to translate them, but ensure they still describe the link's destination correctly.

**Consistency**

- [ ] Ensure that the terminology and style are consistent throughout the document.
- [ ] If the document refers to other sections within itself, double-check that these references are accurate post-translation.

**Cultural Considerations**

- [ ] Ensure that examples, metaphors, or idioms are culturally relevant or adapt them so that they are.
- [ ] Avoid terms or examples that might be considered offensive or inappropriate in the target language or culture.

**Images and Alt Text**

- [ ] If the document contains images with text, consider whether the text in the image needs to be translated.
- [ ] Translate the alt text (a description of the image for accessibility purposes) for each image.

**Feedback**

- [ ] If there are parts of the original document that are unclear or might be misunderstood, communicate with the original author or a knowledgeable person to seek clarity.

Remember, the main goal of the translation is to make the content as accessible and clear to the new audience as it was to the original audience. Always prioritize clarity and accuracy.

Thank you for your interest in contributing; we're excited to have you! Reach out on the [`#docs` channel on Discord](https://discord.com/invite/tauri) if you have any questions along the way.
19 changes: 19 additions & 0 deletions .github/labeler.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# See https://github.com/actions/labeler

i18n:
- src/content/docs/es/**/*
- src/content/docs/fr/**/*
- src/content/docs/it/**/*
- src/content/docs/zh-cn/**/*

"i18n: es":
- src/content/docs/es/**/*

"i18n: fr":
- src/content/docs/fr/**/*

"i18n: it":
- src/content/docs/it/**/*

"i18n: zh-cn":
- src/content/docs/zh-cn/**/*
Loading

0 comments on commit 9353db3

Please sign in to comment.