From 019d80976dfc6b262200c1f85451f21d52459fa4 Mon Sep 17 00:00:00 2001 From: Manny Becerra <39503964+mannybecerra@users.noreply.github.com> Date: Mon, 31 Aug 2020 20:40:40 -0700 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=83=20Adds=20Frequently=20Asked=20Ques?= =?UTF-8?q?tions=20(FAQs)=20Page=20(Issue=20#246)=20(#288)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Initial Frequently Asked Questions (FAQs) page that is a child to the Documentation page and cross-linked accordingly. Corresponds to issue #246 * Cross-referencing and linking to the new FAQs page (b55ec86) from the Contributing Guidelines docs. Corresponds to issue #246 * Doh! Inadvertently removed the `Get Help` sub-heading under c98290e; this commit adds `Get Help` back * linting - updating unordered bullets to dash instead of asterisk * adding copy and link to joining the Self-Defined app Slack community per feedback from Tatiana * Update 11ty/documentation/index.md Feedback from Tatiana Co-authored-by: Tatiana Mac * Update 11ty/documentation/frequently-asked-questions.md Copy feedback from Tatiana Co-authored-by: Tatiana Mac * tidying up copy for FAQs page per Tatiana feedback, specifically under `Open PR` * additional copy cleanup and updates per Tatiana PR feedback * converting the FAQ markdown page (b55ec86, 5552abd) to a njk html template since we're utilizing dl, dt & dd markup tags for our FAQ content. Changes include corresponding CSS rules for dl and dt tags and minor punctuation update in the contributing guidelines. Addresses issue #246 Co-authored-by: Manny Becerra Co-authored-by: Tatiana Mac --- .../frequently-asked-questions.njk | 35 +++++++++++++++++++ 11ty/documentation/index.md | 5 +-- CONTRIBUTING.md | 5 ++- assets/css/components/_lists.scss | 6 +++- 4 files changed, 47 insertions(+), 4 deletions(-) create mode 100644 11ty/documentation/frequently-asked-questions.njk diff --git a/11ty/documentation/frequently-asked-questions.njk b/11ty/documentation/frequently-asked-questions.njk new file mode 100644 index 00000000..12737286 --- /dev/null +++ b/11ty/documentation/frequently-asked-questions.njk @@ -0,0 +1,35 @@ +--- +title: FAQs +parent: + title: Documentation + href: '/documentation' +--- + +

Answers to frequently asked questions.

+ +
+
When should I open an issue versus a pull request (PR)?
+
+

Open PR

+

Some examples of when you may want to open a PR:

+
    +
  • Correct misspellings
    • +
  • Fix broken links
    • +
  • Add definitions/nuance/translations to words that exist on the site already but are undefined/partially defined/could use more nuance
    • +
  • Resolve issues that already exist
    • +
+

Generally speaking, if you know how to open a PR in order to fix the issue, doing that is best. However, we recognise that it requires knowledge of GitHub and code to some degree, which is a form of gatekeeping. We're currently working on ways to improve/remove this barrier to entry. We also are always willing to help if you'd like to learn. Reach out via our Slack community

+
+
+

Open Issue

+

Some examples of when you may want to open an issue:

+
    +
  • Are not sure how to open a PR but have a suggestion
    • +
  • Express concern or ask a question around a term that you don't have clear prescriptive feedback around
    • +
  • Add a new term that is not yet listed (with or without definition)
    • +
  • Add or enhance a feature that you're unsure is desired
    • +
+
+
+ +

Related: Contributing Guidelines

diff --git a/11ty/documentation/index.md b/11ty/documentation/index.md index 8df093fc..af992485 100644 --- a/11ty/documentation/index.md +++ b/11ty/documentation/index.md @@ -4,6 +4,7 @@ title: Docs As always, documentation is a work in progress. However, this is what we have so far: -- [Examples](/documentation/examples/): Grab-and-go definition examples -- [Front Matter](/documentation/front-matter/): Configuration possibilities through front matter - [Development & Build](/documentation/development/): Notes for developing the site +- [Front Matter](/documentation/front-matter/): Configuration possibilities through front matter +- [Examples](/documentation/examples/): Grab-and-go definition examples +- [FAQs](/documentation/frequently-asked-questions): Answers to frequently asked questions diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a1845cea..69ac085a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,7 +17,7 @@ Please remember that the contributing team is always here to [help](#get-help). Below we describe two ways for you to get started: through [issues](#version-1-issues) or [pull requests](#version-2-pull-requests). --- -**Note:** We also have [documentation](https://www.selfdefined.app/documentation/) that covers development and build processes, provides examples, and describes front matter configurations. +**Note:** We also have [documentation](https://www.selfdefined.app/documentation/) that covers development and build processes, provides examples, frequently asked questions, and describes front matter configurations. --- @@ -81,10 +81,13 @@ For this tutorial we will take the word «Obsessive Compulsive Disorder», as it We have created some examples that you can use as the baseline for your work. Take a look at the [File Examples](https://www.selfdefined.app/documentation/examples/) section of our documentation. +**Related:** [When should I open an issue versus a pull request (PR)?](https://www.selfdefined.app/documentation/frequently-asked-questions/#when-should-i-open-an-issue-versus-a-pull-request) + ## Get Help If you've already tried reading through our [documentation](https://www.selfdefined.app/documentation/) and are stuck, we're here to help and ask your questions: +- Join our [Slack community](https://join.slack.com/t/selfdefined/shared_invite/zt-fczgm8b6-8ZZgHvLutNDXo~NjwaL7Iw). - Reach out to [@SelfDefinedApp](https://www.twitter.com/selfdefinedapp) on Twitter. - File an [issue](https://github.com/tatianamac/selfdefined/issues/new) if you think our docs are missing some information that might be helpful. - Contact . diff --git a/assets/css/components/_lists.scss b/assets/css/components/_lists.scss index 93fcf66d..b384dbf0 100644 --- a/assets/css/components/_lists.scss +++ b/assets/css/components/_lists.scss @@ -1,4 +1,4 @@ -ol { +ol, dl { margin: 0; padding: 0 0 0 1em; } @@ -21,6 +21,10 @@ li { } } +dt { + font-weight: $bold; +} + .list-semicolon { list-style: none; margin: 0;