From f4de779ed8bc3ce552430b46f6fe1fe8600217e7 Mon Sep 17 00:00:00 2001 From: Lev Chelyadinov Date: Sun, 24 Sep 2023 22:05:20 +0200 Subject: [PATCH] feat: refresh the FAQ --- .../current/get-started/faq.md | 97 ++++++------------- .../current/get-started/faq.md | 97 ++++++------------- 2 files changed, 62 insertions(+), 132 deletions(-) diff --git a/i18n/en/docusaurus-plugin-content-docs/current/get-started/faq.md b/i18n/en/docusaurus-plugin-content-docs/current/get-started/faq.md index 6418b64928..daecfad948 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/get-started/faq.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/get-started/faq.md @@ -7,97 +7,62 @@ pagination_next: guides/index :::info -You can ask your question in [telegram chat](https://t.me/feature_sliced) / [github-issues](https://github.com/feature-sliced/documentation/issues) / [github-discussions](https://github.com/feature-sliced/documentation/discussions) +You can ask your question in our [Telegram chat][telegram], [Discord community][discord], and [GitHub Discussions][github-discussions]. ::: -### Structure = Architecture? +### Is there a toolkit or a linter? -Architecture defines abstractions and relations between them (shared/features/pages/...) +There is an official ESLint config — [@feature-sliced/eslint-config][eslint-config-official], and an ESLint plugin — [@conarti/eslint-plugin-feature-sliced][eslint-plugin-conarti], created by Aleksandr Belous, a community member. You're welcome to contribute to these projects or start your own! -*But without a proper structure, it's difficult to design a good architecture* - -### Do I need a methodology only for "understanding and clarity" of what is happening in the project? - -Rather yes than no - -*Otherwise, you have to read huge directories `components/`...* - -### Does a novice developer need an architecture/methodology? - -Rather yes than no - -*Usually, when you design and develop a project in one person, everything goes smoothly. But if there are pauses in development, new developers are added to the team - then problems come* - -### Why do we need another methodology when everything is based on principles? - -Answered [here](/docs/about/motivation) - -### Where can I find examples of applying the methodology? - -There are only such ones in the public domain so far, not all of them have been fully adapted to the latest version - -*In the near future, the list will be updated and will be placed in a separate section* - -- [Internal Examples](https://github.com/feature-sliced/examples) -- [External Examples](/examples) +### Where to store the layout/template of pages? -*Also, you can get acquainted with our [guides](/docs/guides) and [tutorials](/docs/get-started)* +If you need plain markup layouts, you can keep them in `shared/ui`. If you need to use higher layers inside, there are a few options: -### Are there some useful resources / articles / etc about FSD and related things? +- Perhaps you don't need layouts at all? If the layout is only a few lines, it might be reasonable to duplicate the code in each page rather than try to abstract it. +- If you do need layouts, you can have them as separate widgets or pages, and compose them in your router configuration in App. Nested routing is another option. - +### What is the difference between a feature and an entity? -### The project is written on feature-slices v1, how to update and is it worth it? +An _entity_ is a real-life concept that your app is working with. A _feature_ is an nteraction that provides real-life value to your app’s users, the thing people want to do with your entities. -Answered [here](/docs/guides/migration/from-v1) +For more information, along with examples, see the Reference page on [slices][reference-entities]. ### Can I embed pages/features/entities into each other? -Answered [here](/docs/reference/slices-segments#slices) +Yes, but this embedding should happen in higher layers. For example, inside a widget, you can import both features and then insert one feature into another as props/children. -### How do I work with the authorization context? - -Answered [here](/docs/guides/examples/auth) +You cannot import one feature from another feature, this is prohibited by the [**import rule on layers**][import-rule-layers]. ### What about Atomic Design? -The current version of the methodology does not oblige, but also does not prohibit the use of Atomic Design together with Feature-Sliced Design - -At the same time, Atomic Design [is well applied](https://t.me/feature_sliced/1653) for the `ui` segment of modules - -### What is the difference between feature and entity? +The current version of the methodology does not require nor prohibit the use of Atomic Design together with Feature-Sliced Design. -- `Entity` - business **entity** - - blog-post / user / order / product / ... -- `Feature` - business feature, **action on an entity** - - create-blog-post / login-by-oauth / edit-account / publish-video / ... +For example, Atomic Design [can be applied well](https://t.me/feature_sliced/1653) for the `ui` segment of modules. -See also [comparison reference](/docs/reference/layers), [viewer implementation of logic by layers](/docs/guides/examples/auth) +### Are there any useful resources/articles/etc. about FSD? -### Where to store the layout/template of pages? - -It is better to store general templates for markup in `shared/ui`, but there are [different cases](https://github.com/feature-sliced/documentation/discussions/129) +Yes! -### Will there be a toolkit / linters? +### Why do I need Feature-Sliced Design? -It will be, at the moment - in development =) +It helps you and your team to quickly overview the project in terms of its main value-bringing components. A standardized architecture helps to speed up onboarding and resolves debates about code structure. See the [motivation][motivation] page to learn more about why FSD was created. -> For now, to sort / prohibit imports, you can use -> -> - `eslint-plugin-import` -> - `eslint-plugin-simple-import-sort` -> - `eslint-plugin-boundaries` -> - `dependency-cruiser` -> -> See [basic config example](https://gist.github.com/azinit/4cb940a1d4a3e05ef47e15aa18a9ecc5) +### Does a novice developer need an architecture/methodology? -### Can I store the features used on one page directly in the page directory? +Rather yes than no -The methodology strongly recommends against doing this, since each module has a corresponding place in the structure. +*Usually, when you design and develop a project in one person, everything goes smoothly. But if there are pauses in development, new developers are added to the team - then problems come* -Otherwise , there is a risk of complicating the project's code base +### How do I work with the authorization context? -> *"Today, the feature can only be used on one page. Next week - on three. And in a month - it may be removed at all. We cannot predict the future, and we need to refrain from premature optimizations every time"* +Answered [here](/docs/guides/examples/auth) -*See also the example from [tutorial](/docs/get-started/tutorial#normal-approach)* +[import-rule-layers]: /docs/reference/layers#import-rule-on-layers +[reference-entities]: /docs/reference/layers#entities +[eslint-config-official]: https://github.com/feature-sliced/eslint-config +[eslint-plugin-conarti]: https://github.com/conarti/eslint-plugin-feature-sliced +[motivation]: /docs/about/motivation +[telegram]: https://t.me/feature_sliced +[discord]: https://discord.gg/S8MzWTUsmp +[github-discussions]: https://github.com/feature-sliced/documentation/discussions diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/get-started/faq.md b/i18n/ru/docusaurus-plugin-content-docs/current/get-started/faq.md index 1b58c57975..3a8e25ae44 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/get-started/faq.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/get-started/faq.md @@ -7,97 +7,62 @@ pagination_next: guides/index :::info -Свой вопрос можно задать в [telegram-чате](https://t.me/feature_sliced) / [github-issues](https://github.com/feature-sliced/documentation/issues) / [github-discussions](https://github.com/feature-sliced/documentation/discussions) +Свой вопрос можно задать в [Telegram-чате][telegram], [Discord-сообществе][discord] и [GitHub Discussions][github-discussions]. ::: -### Структура = Архитектура? {#structure--architecture} +### Существует ли тулкит или линтер? {#is-there-a-toolkit-or-a-linter} -Архитектура - про абстракции и выстраивание связей между ними (shared/features/pages/...) +Есть официальный конфиг для ESLint — [@feature-sliced/eslint-config][eslint-config-official], и плагин для ESLint — [@conarti/eslint-plugin-feature-sliced][eslint-plugin-conarti], созданный участником сообщества Александром Белоусом. Мы будем рады вашим вкладам в эти проекты или созданию своих! -*Но без надлежащей структуры - хорошей архитектуры не сделать* - -### Нужна ли мне методология только для "понимания и ясности" что происходит в проекте? {#do-i-need-a-methodology-only-for-understanding-and-clarity-of-what-is-happening-in-the-project} - -Скорее да, чем нет - -*Иначе приходится читать огромные директории `components/`...* - -### Нужна ли архитектура/методология начинающему разработчику? {#does-a-novice-developer-need-an-architecturemethodology} - -Скорее да, чем нет - -*Обычно, когда проектируешь разрабатываешь проект в одно лицо - все идет гладко. Но если появляются паузы в разработке, добавляются новые разработчики в команду - тогда-то и наступают проблемы* - -### Зачем нужна еще одна методология, когда все строится на принципах? {#why-do-we-need-another-methodology-when-everything-is-based-on-principles} - -Ответили [здесь](/docs/about/motivation) - -### Где найти примеры применения методологии? {#where-can-i-find-examples-of-applying-the-methodology} - -В открытом доступе пока есть только такие, не все до конца адаптированы до последней версии - -*В ближайшее время список будет пополняться и будет вынесен в отдельный раздел* - -- [Internal Examples](https://github.com/feature-sliced/examples) -- [External Examples](/examples) +### Где хранить layout/template страниц? {#where-to-store-the-layouttemplate-of-pages} -*Также можно ознакомиться с [гайдами](/docs/guides) и [туториалами](/docs/get-started)* +Если вам нужны простые шаблоны разметки, вы можете хранить их в `shared/ui`. Если вам нужно использовать более высокие слои, есть несколько вариантов: -### Есть ли какие-нибудь полезные ресурсы/статьи/и т.д. по FSD и связанным вещам? {#are-there-some-useful-resources--articles--etc-about-fsd-and-related-things} +- Возможно, вам вообще не нужны лейауты? Если макет состоит всего из нескольких строк, разумно будет дублировать код в каждой странице, а не пытаться абстрагировать его. +- Если вам нужны лейауты, вы можете хранить их как отдельные виджеты или страницы, и компоновать их в конфигурации роутера в App. Вложенный роутинг — еще один вариант. - +### В чем отличие feature от entity? {#what-is-the-difference-between-feature-and-entity} -### Проект написан на feature-slices v1, как обновиться и стоит ли? {#the-project-is-written-on-feature-slices-v1-how-to-update-and-is-it-worth-it} +_Entity_ — это понятие из реальной жизни, с которым работает ваше приложение.. _Feature_ — это взаимодействие, представляющее реальную ценность для пользователей; что-то, что люди хотят делать с сущностями. -Ответили [здесь](/docs/guides/migration/from-v1) +Для получения дополнительной информации, а также примеров, см. страницу [про слайсы][reference-entities] в разделе Reference. ### Могу ли я вкладывать страницы/фичи/сущности друг в друга? {#can-i-embed-pagesfeaturesentities-into-each-other} -Ответили [здесь](/docs/reference/slices-segments#slices) +Да, но это вложение должно происходить в более высоких слоях. Например, внутри виджета вы можете импортировать обе фичи, а затем вставить одну фичу в другую через пропсы/вложение. -### Как мне работать с контекстом авторизации? {#how-do-i-work-with-the-authorization-context} - -Ответили [здесь](/docs/guides/examples/auth) +Вы не можете импортировать одну фичу из другой фичи, это запрещено [**правилом импортов для слоёв**][import-rule-layers]. ### А что с Atomic Design? {#what-about-atomic-design} -Текущая версия методологии не обязывает, но и не запрещает использовать Atomic Design вместе с Feature-Sliced Design - -При этом Atomic Design [хорошо применяется](https://t.me/feature_sliced/1653) для `ui` сегмента модулей - -### В чем отличие feature и entity? {#what-is-the-difference-between-feature-and-entity} +Текущая версия методологии не обязывает, но и не запрещает использовать Atomic Design вместе с Feature-Sliced Design. -- `Entity` - бизнесовая **сущность** - - blog-post / user / order / product / ... -- `Feature` - бизнесовая фича, **действие над сущностью** - - create-blog-post / login-by-oauth / edit-account / publish-video / ... +При этом Atomic Design [хорошо применяется](https://t.me/feature_sliced/1653) для `ui` сегмента модулей. -См. также [справочную информацию по сравнению](/docs/reference/layers), [реализация viewer логики по слоям](/docs/guides/examples/auth) +### Есть ли какие-нибудь полезные ресурсы/статьи/т.д. по FSD? {#are-there-any-useful-resourcesarticlesetc-about-fsd} -### Где хранить layout/template страниц? {#where-to-store-the-layouttemplate-of-pages} - -Общие шаблоны для разметки лучше хранить в `shared/ui`, но бывают [разные случаи](https://github.com/feature-sliced/documentation/discussions/129) +Да! -### А будет тулкит / линтеры? {#will-there-be-a-toolkit--linters} +### Зачем мне нужен Feature-Sliced Design? {#why-do-i-need-feature-sliced-design} -Будет, на данный момент - в разработке =) +Он помогает вам и вашей команде быстро ознакомиться с проектом с точки зрения его основных компонентов, приносящих бизнес-ценность. Стандартизированная архитектура помогает ускорить онбординг и разрешать споры о структуре кода. См. страницу [Мотивация][motivation], чтобы узнать больше о том, почему FSD был создан. -> Пока что, для сортировки / запрета импортов можно воспользоваться -> -> - `eslint-plugin-import` -> - `eslint-plugin-simple-import-sort` -> - `eslint-plugin-boundaries` -> - `dependency-cruiser` -> -> См. [базовый пример конфига](https://gist.github.com/azinit/4cb940a1d4a3e05ef47e15aa18a9ecc5) +### Нужна ли архитектура/методология начинающему разработчику? {#does-a-novice-developer-need-an-architecturemethodology} -### Могу ли я хранить фичи используемые на одной странице прямо в директории страницы? {#can-i-store-the-features-used-on-one-page-directly-in-the-page-directory} +Скорее да, чем нет -Методология крайне не рекомендует так делать, поскольку каждому модулю есть соответствующее место в структуре +*Обычно, когда проектируешь разрабатываешь проект в одно лицо - все идет гладко. Но если появляются паузы в разработке, добавляются новые разработчики в команду - тогда-то и наступают проблемы* -Иначе - есть риск усложнения кодовой базы проекта +### Как мне работать с контекстом авторизации? {#how-do-i-work-with-the-authorization-context} -> *"Сегодня фича может использоваться только на одной странице. На следующей неделе - на трех. А через месяц - ее может не быть совсем. Мы не можем предсказывать будущее, и нужно каждый раз воздерживаться от преждевременных оптимизаций"* +Ответили [здесь](/docs/guides/examples/auth) -*См. также пример из [tutorial](/docs/get-started/tutorial#usual-approach)* +[import-rule-layers]: /docs/reference/layers#import-rule-on-layers +[reference-entities]: /docs/reference/layers#entities +[eslint-config-official]: https://github.com/feature-sliced/eslint-config +[eslint-plugin-conarti]: https://github.com/conarti/eslint-plugin-feature-sliced +[motivation]: /docs/about/motivation +[telegram]: https://t.me/feature_sliced +[discord]: https://discord.gg/S8MzWTUsmp +[github-discussions]: https://github.com/feature-sliced/documentation/discussions