docs: adds website contributing doc (#7064)

* docs: adds website contributing doc

### What does this PR do?

Adds a website contributing doc with some initial information /
templates on how to write documentation so we have some consistency in
writing documentation.

### Screenshot / video of UI

<!-- If this PR is changing UI, please include
screenshots or screencasts showing the difference -->

N/A

### What issues does this PR fix or reference?

<!-- Include any related issues from Podman Desktop
repository (or from another issue tracker). -->

N/A, some small notes I had written while writing website documentation

### How to test this PR?

<!-- Please explain steps to verify the functionality,
do not forget to provide unit/component tests -->

N/A, it's docs

Signed-off-by: Charlie Drage <charlie@charliedrage.com>

* another section for standard templates

Signed-off-by: Charlie Drage <charlie@charliedrage.com>

---------

Signed-off-by: Charlie Drage <charlie@charliedrage.com>
This commit is contained in:
Charlie Drage 2024-05-03 10:59:53 -04:00 committed by GitHub
parent 6526388812
commit d48f4cc464
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 152 additions and 0 deletions

View file

@ -17,6 +17,7 @@ that we follow.
- [Communication](#communication)
- [Code Architecture](#code-architecture)
- [Maintainer Tasks](#maintainer-tasks)
- [Website Contributions](#website-contributions)
## Reporting Issues
@ -375,3 +376,7 @@ Your responsibilities include:
- Evaluating the severity of new issues. If an issue is classified as "critical" or "high priority" and requires immediate attention, tag a maintainer in the issue and notify them via the public community channel.
- Identifying issues that are simple to resolve and marking them as "good first issue," thereby encouraging newcomers to contribute to the project.
- Evaluating any stale / lingering pull requests and pinging the respective contributors. If the pull request has been opened for an extensive amount of time, ping someone to contact the contributor / push any changes required to get it merged in. If there is no communication / the pull request is stale, close them.
## Website Contributions
See our [WEBSITE_CONTRIBUTING](/WEBSITE_CONTRIBUTING.md) documentation for more details on how to contribute to the website.

147
WEBSITE_CONTRIBUTING.md Normal file
View file

@ -0,0 +1,147 @@
# Contributing to podman-desktop.io
Thank you for your interest in improving the website!
The below information outlines details on how to both contribute as well as our documentation "templates" and criteria.
## Documentation information
All documentation is located within [/website/docs](/website/docs).
The website is built using [docusaurus](https://docusaurus.io/) and published to [podman-desktop.io](https://podman-desktop.io) on each commit.
## Previewing the website
The website can be previewed by running the following command:
```sh
yarn website:dev
```
Which will automatically open your browser to `localhost:3000`.
You may also build a "production-like" environment by using:
```sh
yarn website:prod
```
## Pull request previews
On each pull request we use ArgosCI to do screenshot-comparison to check for any major changes. This may have to be manually approved.
You can also find the Netlify link within the "Checks" section of the pull request for a live-preview of your documentation changes.
## Formatting and lint checking
Formatting and lint checking can be examined by running the following commands:
```sh
# Markdown formatting
yarn format:check
yarn format:fix
# Markdown lint checking
yarn markdownlint:check
yarn markdownlint:fix
```
## Screenshot and video standards
We want to maintain **consistency** between screenshots that make it readable for all users.
### Screenshots
Ideally your screenshot should be:
- 1060px width
- 710px height
- Have a very small border
- Ideally have a transparent background
This matches the ratio of Podman Desktop's default size of 1050x700 as well as gives a few pixels spacing for a border.
Tips:
- Use a **red** circle to emphasize points of interest / draw the users eyes towards.
- If you are unable to put the entire example in the screenshot, **zoom out** Podman Desktop (View -> Zoom Out) and re-take the screenshot.
### Video & gifs
Gifs and video are acceptable granted they are:
- Small in size (under 3mb)
- Less than 10 seconds long
- Uses compression. For gifs, use software such as [gifski](https://gif.ski/) with CLI commands such as `--fps 10 --quality 70`.
## Templates
Below are some "templates" to be used when writing documentation.
These do not encompass all scenarios, but gives you a foundation of how to write documentation.
### Metadata
All files should have the following metadata:
```
---
title: Your title
description: Small one sentence description
sidebar_position: 1 # Weight depending on the position you want
keywords: [multiple, keywords, as-needed]
tags: [category]
---
```
### Standard template
The most common template that requires a prerequisites section and "tutorial" / procedural section in order to teach the user something.
```markdown
# <Title of the section>
<Brief description of what this will teach the user>
#### Prerequisites <optional>
<Bullet point list of prerequisites>
#### Procedure
<Typically a numbered list of steps, although not an enforced standard>
#### Verification <optional>
<Steps to verify that the procedure worked as intended>
#### Additional resources <optional>
Links to further information (could be podman desktop documentation, or outside links)
```
### Troubleshooting
A "typical" list of troubleshooting scenarios and their solutions.
```markdown
# <Title of the troubshooting section>
## <Specific issue>
One sentence general information about the issue
### Issues encountered: <this usually will contain log outputs typically encountered, below are good examples>
`docker-credential-desktop` missing:
<log output in code block>
Authentication access:
<log output in code block>
### Solution:
Delete the `~/.docker/config` to clear any errors. <example solution>
```