From d429b6593398029fb81bd1e536e09a24aa59852e Mon Sep 17 00:00:00 2001 From: Sean T Allen Date: Sun, 18 Feb 2024 08:57:05 -0500 Subject: [PATCH] Add FAQ overview (#943) --- docs/blog/posts/last-week-in-pony-022623.md | 2 +- docs/community/index.md | 2 +- docs/faq/index.md | 5 +++++ docs/learn/getting-help.md | 2 +- mkdocs.yml | 1 + 5 files changed, 9 insertions(+), 3 deletions(-) create mode 100644 docs/faq/index.md diff --git a/docs/blog/posts/last-week-in-pony-022623.md b/docs/blog/posts/last-week-in-pony-022623.md index 2307d10b..1aa0aad3 100644 --- a/docs/blog/posts/last-week-in-pony-022623.md +++ b/docs/blog/posts/last-week-in-pony-022623.md @@ -59,7 +59,7 @@ And if it doesn't sound interesting, you can join and steer the conversation in We like to take a moment in each Last Week in Pony to highlight a community resource. There are many community resources that can go unappreciated until _just the right time_ when someone hops into the Ponylang Zulip asking a question or facing a problem we have all had at one time or another. Well here in Last Week in Pony, we make it **just the right time** to highlight one of our excellent community resources. -This week we are looking at Pony [Frequently Asked Questions (FAQs)](https://www.ponylang.io/faq/), in particular whether a [ref can become a val](https://www.ponylang.io/faq/code/#ref-to-val). +This week we are looking at Pony [Frequently Asked Questions (FAQs)](https://www.ponylang.io/faq/index.md), in particular whether a [ref can become a val](https://www.ponylang.io/faq/code/#ref-to-val). It is not uncommon to start learning Pony by using a lot of implicit and explicit `ref` reference capabilities. This is because `ref` is perhaps the most familiar capability when coming from other languages. With a `ref` we are creating a mutable, local reference; we can locally alias this `ref` as many times as we want. Joy! But wait...what if we want to mutate up to a point and then "lock" that data into being immutable? This is usually what someone who wants to go from a `ref` to a `val` is trying to do -- start with a locally mutable `ref` which is then "locked" into being a globally immutable `val`. However this does not work and they get frustrated. The quick solutions are: diff --git a/docs/community/index.md b/docs/community/index.md index 321c531b..1f616414 100644 --- a/docs/community/index.md +++ b/docs/community/index.md @@ -3,4 +3,4 @@ The most important community resources for those who are new to Pony are: * Pony [community Zulip](https://ponylang.zulipchat.com) -* The [frequently asked questions](/faq/about-pony.md) section of this website. +* The [frequently asked questions](/faq/index.md) section of this website. diff --git a/docs/faq/index.md b/docs/faq/index.md new file mode 100644 index 00000000..0c24d0b2 --- /dev/null +++ b/docs/faq/index.md @@ -0,0 +1,5 @@ +# FAQ + +We don't answer every question in our FAQs. We probably don't answer the question you have right now, but we do answer the questions that come up often in our [beginner help stream](https://ponylang.zulipchat.com/#narrow/stream/189985-beginner-help). It makes it easy for us to point people to the answer. + +If your question isn't answered here, check out our [getting help guide](https://www.ponylang.io/learn/getting-help/). diff --git a/docs/learn/getting-help.md b/docs/learn/getting-help.md index 7268a741..9782f321 100644 --- a/docs/learn/getting-help.md +++ b/docs/learn/getting-help.md @@ -8,7 +8,7 @@ If you run into trouble while you are learning Pony, don't worry, we've got you The [beginner help](https://ponylang.zulipchat.com/#narrow/stream/189985-beginner-help) stream is a good starting point for basic questions. If you need more information on what is considered appropriate or inappropriate behaviour, check out our [Code of Conduct](https://github.com/ponylang/ponyc/blob/main/CODE_OF_CONDUCT.md). -Many folks encounter the same issues or have the same questions, be sure to give the [frequently asked questions](/faq/about-pony.md) section of this website a read. +Many folks encounter the same issues or have the same questions, be sure to give the [frequently asked questions](/faq/index.md) section of this website a read. Think you've found a bug? It's quite possible. Pony is a relatively young language that is still changing at a rapid pace and bugs do happen. Your best bet. Write to the mailing list with your issue and verify that you are experiencing an issue. Once a more knowledge member of the community confirms you are experiencing a bug, open an issue. diff --git a/mkdocs.yml b/mkdocs.yml index fbd44bcd..dda5a975 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -163,6 +163,7 @@ nav: - Blog: - "blog/index.md" - FAQ: + - Overview: "faq/index.md" - About Pony: "faq/about-pony.md" - Code: "faq/code.md" - Comparisons to Other Languages: "faq/comparisons.md"