From e891db6fae7e05f59072b85385dee02fa2a7b5d7 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 17 May 2024 16:38:45 -0400 Subject: [PATCH] Add Persian overview page, refactor English pages --- content/en/docs/_index.md | 1 - .../docs/{concepts/_index.md => concepts.md} | 4 +- .../_index.md => contribution-guidelines.md} | 4 +- .../docs/{examples/_index.md => examples.md} | 6 ++- content/en/docs/overview.md | 48 +++++++++++++++++++ content/en/docs/overview/_index.md | 36 -------------- content/fa/docs/_index.md | 1 - content/fa/docs/overview.md | 36 ++++++++++++++ content/no/docs/_index.md | 1 - package.json | 5 ++ 10 files changed, 99 insertions(+), 43 deletions(-) rename content/en/docs/{concepts/_index.md => concepts.md} (99%) rename content/en/docs/{contribution-guidelines/_index.md => contribution-guidelines.md} (99%) rename content/en/docs/{examples/_index.md => examples.md} (99%) create mode 100644 content/en/docs/overview.md delete mode 100644 content/en/docs/overview/_index.md create mode 100644 content/fa/docs/overview.md diff --git a/content/en/docs/_index.md b/content/en/docs/_index.md index e4a577ec9a6..955c9653fc3 100755 --- 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 b/content/en/docs/concepts.md similarity index 99% rename from content/en/docs/concepts/_index.md rename to content/en/docs/concepts.md index 4a5d1755f07..ad99cd88050 100644 --- a/content/en/docs/concepts/_index.md +++ b/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/content/en/docs/contribution-guidelines/_index.md b/content/en/docs/contribution-guidelines.md similarity index 99% rename from content/en/docs/contribution-guidelines/_index.md rename to content/en/docs/contribution-guidelines.md index 1f9fd09420f..c10be2c237d 100644 --- a/content/en/docs/contribution-guidelines/_index.md +++ b/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 b/content/en/docs/examples.md similarity index 99% rename from content/en/docs/examples/_index.md rename to content/en/docs/examples.md index 2b4a0f07b86..e77416363fc 100755 --- a/content/en/docs/examples/_index.md +++ b/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 new file mode 100644 index 00000000000..23f9f6d2662 --- /dev/null +++ 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 deleted file mode 100644 index 5c51c56bf8f..00000000000 --- a/content/en/docs/overview/_index.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -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/fa/docs/_index.md b/content/fa/docs/_index.md index 0135b7843f1..48517671dec 100755 --- 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 new file mode 100644 index 00000000000..23c0f71c319 --- /dev/null +++ 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 index 992f477c7e4..4d85c086f55 100755 --- 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 index 901e931deb3..f000869f815 100644 --- 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 } }