Add Persian overview page, refactor English pages (#303)

google · May 28, 2024 · f5fc85a · f5fc85a
1 parent 3f24116
commit f5fc85a
Show file tree

Hide file tree

Showing 10 changed files with 99 additions and 43 deletions.
diff --git a/content/en/docs/_index.md b/content/en/docs/_index.md
@@ -2,7 +2,6 @@
 title: Documentation
 linkTitle: Docs
 menu: {main: {weight: 20}}
-weight: 20
 ---
 
 {{% pageinfo %}}

diff --git a/content/en/docs/concepts/_index.md → content/en/docs/concepts.md b/content/en/docs/concepts/_index.md → content/en/docs/concepts.md
@@ -1,12 +1,14 @@
 ---
 title: Concepts
-weight: 4
 description: >
   What does your user need to understand about your project in order to use it - or potentially contribute to it?
+weight: 4
 ---
 
 {{% pageinfo %}}
+
 This is a placeholder page that shows you how to use this template site.
+
 {{% /pageinfo %}}
 
 For many projects, users may not need much information beyond the information in the [Overview](/docs/overview/), so this section is **optional**. However if there are areas where your users will need a more detailed understanding of a given term or feature in order to do anything useful with your project (or to not make mistakes when using it) put that information in this section. For example, you may want to add some conceptual pages if you have a large project with many components and a complex architecture.

diff --git a/...en/docs/contribution-guidelines/_index.md → content/en/docs/contribution-guidelines.md b/...en/docs/contribution-guidelines/_index.md → content/en/docs/contribution-guidelines.md
@@ -1,13 +1,15 @@
 ---
 title: Contribution Guidelines
-weight: 10
 description: How to contribute to the docs
+weight: 10
 ---
 
 {{% pageinfo %}}
+
 These basic sample guidelines assume that your Docsy site is deployed using Netlify and your files are stored in GitHub. You can use the guidelines "as is" or adapt them with your own instructions: for example, other deployment options, information about your doc project's file structure, project-specific review guidelines, versioning guidelines, or any other information your users might find useful when updating your site. [Kubeflow](https://github.com/kubeflow/website/blob/master/README.md) has a great example.
 
 Don't forget to link to your own doc repo rather than our example site! Also make sure users can find these guidelines from your doc repo README: either add them there and link to them from this page, add them here and link to them from the README, or include them in both locations.
+
 {{% /pageinfo %}}
 
 We use [Hugo](https://gohugo.io/) to format and generate our website, the

diff --git a/content/en/docs/examples/_index.md → content/en/docs/examples.md b/content/en/docs/examples/_index.md → content/en/docs/examples.md
@@ -1,12 +1,14 @@
 ---
 title: Examples
-weight: 3
-date: 2017-01-05
 description: See your project in action!
+date: 2017-01-05
+weight: 3
 ---
 
 {{% pageinfo %}}
+
 This is a placeholder page that shows you how to use this template site.
+
 {{% /pageinfo %}}
 
 Do you have any example **applications** or **code** for your users in your repo

diff --git a/content/en/docs/overview.md b/content/en/docs/overview.md
@@ -0,0 +1,48 @@
+---
+title: Overview
+description: Here's where your user finds out if your project is for them.
+weight: 1
+---
+
+{{% pageinfo %}}
+
+This is a placeholder page that shows you how to use this template site.
+
+{{% /pageinfo %}}
+
+The Overview is where your users find out about your project. Depending on the
+size of your docset, you can have a separate overview page (like this one) or
+put your overview contents in the Documentation landing page (like in the Docsy
+User Guide).
+
+Try answering these questions for your user in this page:
+
+## What is it?
+
+Introduce your project, including what it does or lets you do, why you would use
+it, and its primary goal (and how it achieves it). This should be similar to
+your README description, though you can go into a little more detail here if you
+want.
+
+## Why do I want it?
+
+Help your user know if your project will help them. Useful information can
+include:
+
+- **What is it good for?**: What types of problems does your project solve? What
+  are the benefits of using it?
+
+- **What is it not good for?**: For example, point out situations that might
+  intuitively seem suited for your project, but aren't for some reason. Also
+  mention known limitations, scaling issues, or anything else that might let
+  your users know if the project is not for them.
+
+- **What is it _not yet_ good for?**: Highlight any useful features that are
+  coming soon.
+
+## Where should I go next?
+
+Give your users next steps from the Overview. For example:
+
+- [Getting Started](/docs/getting-started/): Get started with $project
+- [Examples](/docs/examples/): Check out some example code!
diff --git a/content/en/docs/overview/_index.md b/content/en/docs/overview/_index.md
diff --git a/content/fa/docs/_index.md b/content/fa/docs/_index.md
@@ -1,7 +1,6 @@
 ---
 title: مستندات
 linkTitle: مستندات
-weight: 20
 menu:
   main:
     weight: 20

diff --git a/content/fa/docs/overview.md b/content/fa/docs/overview.md
@@ -0,0 +1,36 @@
+---
+title: مرور کلی
+description: در اینجا کاربران شما متوجه می‌شوند که آیا پروژه شما برای آن‌ها مناسب است یا نه.
+weight: 1
+---
+
+{{% pageinfo %}}
+
+این یک صفحه جایگزین است که به شما نشان می‌دهد چگونه از این سایت الگو استفاده کنید.
+
+{{% /pageinfo %}}
+
+مرور کلی جایی است که کاربران شما درباره پروژه شما اطلاعات کسب می‌کنند. بسته به اندازه مجموعه مستندات شما، می‌توانید یک صفحه مرور جداگانه داشته باشید (مثل این یکی) یا محتوای مرور خود را در صفحه اصلی مستندات قرار دهید (مثل راهنمای کاربر Docsy).
+
+سعی کنید به این سوالات برای کاربر خود در این صفحه پاسخ دهید:
+
+## این چیست؟
+
+پروژه خود را معرفی کنید، از جمله کاری که انجام می‌دهد یا به شما اجازه می‌دهد انجام دهید، چرا باید از آن استفاده کنید، و هدف اصلی آن (و چگونه به آن دست می‌یابد). این باید شبیه به توضیحات README شما باشد، اگرچه می‌توانید در صورت تمایل به جزئیات بیشتری در اینجا بپردازید.
+
+## چرا می‌خواهم آن را داشته باشم؟
+
+به کاربران خود کمک کنید بدانند آیا پروژه شما به آن‌ها کمک می‌کند یا نه. اطلاعات مفید می‌تواند شامل موارد زیر باشد:
+
+- **برای چه خوب است؟**: چه نوع مشکلاتی را پروژه شما حل می‌کند؟ مزایای استفاده از آن چیست؟
+
+- **برای چه خوب نیست؟**: به عنوان مثال، شرایطی را ذکر کنید که ممکن است به صورت شهودی مناسب پروژه شما به نظر برسد، اما به دلایلی مناسب نیست. همچنین محدودیت‌های شناخته شده، مشکلات مقیاس‌پذیری، یا هر چیز دیگری که ممکن است به کاربران شما بگوید که پروژه برای آن‌ها نیست را ذکر کنید.
+
+- **برای چه _هنوز_ خوب نیست؟**: هر ویژگی مفیدی که به زودی می‌آید را برجسته کنید.
+
+## بعد کجا باید بروم؟
+
+گام‌های بعدی را از مرور کلی به کاربران خود بدهید. به عنوان مثال:
+
+- [شروع کار](/docs/getting-started/): با $project شروع کنید
+- [مثال‌ها](/docs/examples/): برخی کدهای نمونه را بررسی کنید!
diff --git a/content/no/docs/_index.md b/content/no/docs/_index.md
@@ -1,7 +1,6 @@
 ---
 title: TechOS-Dokumentasjon
 linkTitle: Dokumentasjon
-weight: 20
 menu:
   main:
     weight: 20

diff --git a/package.json b/package.json
@@ -38,5 +38,10 @@
     "cross-env": "^7.0.3",
     "hugo-extended": "0.126.1",
     "postcss-cli": "^11.0.0"
+  },
+  "private": true,
+  "prettier": {
+    "proseWrap": "always",
+    "singleQuote": true
   }
 }