feat(layers): Add basic definition of `shared` #79

akaia-shadowfox · 2021-03-21T22:28:34Z

No description provided.

azinit · 2021-03-22T00:37:54Z

Заархивировать бы дискуссию основную)

azinit · 2021-03-22T01:09:49Z

Некритично, но я бы старался именовать ветки в соответствие с gitflow (вродь где-то в похожем такое описывалось как раз)

Глянь как у нас сейчас делают

https://nvie.com/posts/a-successful-git-branching-model/#feature-branches

azinit

Блин, на самом деле, @karina-drummer , я думал от тебя то наоборот простыня добротного такого текста получится))

Я рили стараюсь не придираться особо в PR, но тут... Ну хз, мне кажется как будто ты можешь гораздо мощней написать

Что не так?

Хромает форма документа

Ни структуры, ни форматирования, ни разделения по важности и спойлерам
Хромает и содержание

Почти ничего из изначальной дискуссии (#14) не увидел здесь

Как будто, больше из своих ощущений и представлений писала

Плюс есть ощущение, что написание параллельно на англе - будет у тебя только лишние ресурсы занимать - поэтому сама смотри (как минимум тебе сейчас надо вносить правки и в ru, и в en версию вносить)

azinit · 2021-03-22T01:12:56Z

src/shared/en.md

@@ -0,0 +1,9 @@
+# Namespace: Shared


Ну блен, "just an idea" была же вроде только))

Мб вынесем в concepts/abstractions/shared все же?

@binjospookie тоже так сделал

Те модули, где плейсхолдеры заложила - тоже бы адаптировать

При этом я бы например не клал api (и подобные) строго в shared, т.к. это самодостаточная абстракция

И внутри нее уже может дополнительно расписываться смысл если она лежит в shared/feature и т.д.

Глянь пож, что тут писал

#31 (comment)

Ну блен, "just an idea" была же вроде только))

Мб вынесем в concepts/abstractions/shared все же?

@binjospookie тоже так сделал

Я сделала как предложила, остальное up to you. Никакой структуры объявлено не было, а рандомно раскидывать я бы не стала

Те модули, где плейсхолдеры заложила - тоже бы адаптировать

При этом я бы например не клал api (и подобные) строго в shared, т.к. это самодостаточная абстракция

И внутри нее уже может дополнительно расписываться смысл если она лежит в shared/feature и т.д.

Так мы вроде договорились класть api строго в shared, не?

Я сделала как предложила, остальное up to you. Никакой структуры объявлено не было, а рандомно раскидывать я бы не стала

Я тут скорее к тому - что текст не должен в простыню обычную превращаться, его нужно как-то группировать / разделять по секциям

(как сделаешь окончательный вариант - там посмотрю и по содержанию и по форме - если что сам идеи набросаю)

Так мы вроде договорились класть api строго в shared, не?

Обсудили в войсе

azinit · 2021-03-22T01:13:53Z

src/shared/ru.md

@@ -0,0 +1,9 @@
+# Раздел: Shared


Имхо, слово "Раздел" лишнее)

Оторванное от контекста одиного висящее в заголовке слово тоже не вариант. Просто скопировать название каталога недостаточно, Shared что? Нет никаких указаний на то, что документ как-то принадлежит общей структуре.

Вместо "Раздел" возможно есть смысл написать "Домен" и может быть можно опустить двоеточие: "Домен Shared" / "Shared domain"

Оторванное от контекста одиного висящее в заголовке слово тоже не вариант

Просто скопировать название каталога недостаточно, Shared что? Нет никаких указаний на то, что документ как-то принадлежит общей структуре.

Поч? Не вижу проблем просто оставить # shared`

Вместо "Раздел" возможно есть смысл написать "Домен" и может быть можно опустить двоеточие: "Домен Shared" / "Shared domain"

Оверхед как по мне)

Но если второму ревьюверу норм будет - то оке

azinit · 2021-03-22T01:15:47Z

src/shared/ru.md

@@ -0,0 +1,9 @@
+# Раздел: Shared
+
+## Описание


Не, я конечно за readability и "пиши-сокращай" принципы, но не настолько же :DD

Где структура?

Где форматирование? (все в одну строку на данный момент сейчас читается)

Где разделение инфы на важную (то что видно при поверхностном прочтении) и подробную (то что в спойлерах прячем?)

Где вообще все то, что в дискуссии обсуждалось?

Будет шаблон -- будет и структура

Переносы строк съелись по какой-то причине, поправлю

Жирным шрифтом выделено самое важное, можно даже почти связно это вычитать. Спойлеры -- у нас ведь документация, а не игра-кликер. Приведи примеры документации где используются спойлеры и дай паттерн по которому их нужно использовать, если это действительно хороший приём ( в чём я очень сильно сомневаюсь )

Распиши что я упустила. Это должен быть готовый вывод, стандарт, а не пересказывание обсуждений, я не права?

Есть прекрасные слова "инициатива", "опыт" и "собственное мнение" =)

👌

@karina-drummer
Жирным шрифтом выделено самое важное, можно даже почти связно это вычитать

Сама же ответила на вопрос - "почти связно"))
У меня лично оч расплывчато удается прочесть такое полотно

@karina-drummer
Спойлеры -- у нас документация или игра-кликер? Приведи примеры документации где используются спойлеры и дай паттерн по которому их нужно использовать, если это действительно хороший приём, в чём я очень сильно сомневаюсь

Спойлеры - это способ отделить основную и важную инфу, от подробностей, до которых не все захотят опускаться

#27 (reply in thread)

Да, мб применяется и не во всех документациях (не вспомнишь так сразу), но это способ разбить огромное полотно текста так, чтобы его мог читать пользователь, и не испугался, когда увидел 100+ размытых строк

Думаю тут есть два показательных примера:

Как @sergeysova написал о "потребностях пользователей" (в формате оч развернутого комментария)

Как тот же самый текст оформил я (тут и TL;DR, и разбивка по важности с заботой о читателе, и эмоджи, которые как по мне тоже позволяют смягчить масштабность текста и т.д.)

Само собой, важно не заиграться - и делать спойлеры только там где нужно
Но я пока не вижу других путей, чтобы защищать читателей от огромных простыней текста, без разбивки по важности

Лично я вижу это как "текущий срез по дискуссии", даже если там есть неотвеченные вопросы

Значит их тем более надо упомянуть в доке, чтобы кто-то задал вопрос в чате или дискуссии и помог его решить до конца

Просто у нас уже порядочно дискуссий накопилось, и потихоньку надо начинать делать из них выжимки
Если же ты во время этого отсечешь слишком много инфы из дискуссии (соглашусь, тут тонкая грань оч), то считай все обсуждение на смарку, т.к

никто потом не будет за тебя добавлять выводы (да и ты сама вряд ли потом захочешь дополнять и вычитывать все это снова еще раз)

мало кто потом захочет прочесть еще дискуссию, чтобы понять "Хм, а не наврал ли мне автор - может там в дискуссии содержательно еще что-то есть?"

Хороший пример про Public API: см. изначальную дискуссию и то, как про это написал Саша - про реэкспорты (что было сказано, и как написано по итогу)

Кста оставь ему ревью, ты там второй ревьювер)))

Но я пока не вижу других путей, чтобы защищать читателей от огромных простыней текста, без разбивки по важности

Не нужно никого "защищать", это техническая документация и любой инженер сам должен быть в силах её прочесть, если она будет, насколько это возможно, написана по стандартам технического языка.

Здесь вообще весь раздел скрыт под спойлер. То есть ты видишь заголовок секции, но чтобы эту секцию прочесть – тебе нужно кликать на спойлер.
Детали в документации не скрывают – их там расписывают.

Не нужно никого "защищать", это техническая документация и любой инженер сам должен быть в силах её прочесть, если она будет, насколько это возможно, написана по стандартам технического языка.

Детали в документации не скрывают – их там расписывают.

Обсудим на созвоне сегодня)

src/shared/ru.md

azinit · 2021-03-22T01:32:53Z

Плюс добавил бы в конце все же раздел "См. также"

Пример 1
Пример 2

azinit · 2021-03-22T08:04:27Z

@karina-drummer пиши выше в комментах пока все что считаешь нужным - чуть позже отвечу обязон

Если же отвечать на твой основной месседж...

`TL;DR:` Дерзай как знаешь и считаешь нужным, но вроде как договаривались всю информативную часть из дискуссии в доки переносить

Я несколько раз читала всё что related и по результатам написала строгую техническую выжимку без "может быть" и всяких "А зачем это нужно? Сейчас мы вам ответим, дети", которым место не в доке, а в статьях на medium

Да, почти. Вроде как когда мы все обсуждали задумка была в том, чтобы "оставить после дискуссии весь информативный сухой остаток"
Никто не просит писать в формате супер приближенных к пользователю статей, но тем не менее, как ты и сама замечаешь - у людей постоянно возникают повторяющиеся вопросы и им хочется найти от нас или от документации ответы на них

Другой аспект еще заключается в том - что мы закрываем дискуссию, и чаще всего навсегда, а потому - хочется собрать выводы на текущем срезе и не возвращаться к этому потом
(Поэтому, как мне кажется - любые проблемные моменты, оставшиеся открытые вопросы - должны быть либо подняты и обсуждены core-team ASAP, либо так чтобы и было указано в доке "Пока это открытый вопрос, мы работаем над этим")
Другой момент - что я в доке вообще не увидел ответов на:
- "а что выносить в shared? что там должно хоаниться?",
- "а могу ли я выносить в shared все что возможно захочу переиспользовать?",
- "а что если мы все файлы будем хранить постоянно локально? Что там с DRY"
И про все это - описано в самой дискуссии, потому даже не знаю что тут сказать (да, там скорее в форме рассуждения, но опять же - можем поднять вопрос в самой core-team)

См. что писали по конвертации дискуссии в PR

Да и вообще, какого-то шаблона и конвеншна не было, какое там ещё форматирование нужно я пока слабо представляю, это документация а не конкурс талантов

Насчёт структуры фс — а есть какой-то способ изобразить её так, чтобы она не ехала и не ломалась? Не стала пока добавлять то, что не имеет надёжных инструментов для отображения. Могу тупо скопипастить, конечно.

Здесь ты тоже права - закрепленного формата нет, мы его по сути сейчас как раз и формируем

Можешь посмотреть на имеющиеся примеры от разных людей наших из core-team:

У всех в той или иной мере свой стиль, но тем не менее хочется хотя бы увидеть твои собственные идеи касаемо оформления (может мы все тут вообще все неправильно делаем и ты нас щас всех убедишь)

Так вот, что конкретно я там не увидела? Пока только поняла что стоило "middle-level" вместо "low-level" использовать

Тут не понял, но ладно)

А, сейчас увидела что переносы строк сожрал кто-то, найс

Вот да, потому и полезно проводить self-review перед тем как на код ревью кидать - сама бы наверняка тоже увидела

У нас про self-review и в contributing-guidelines написано

UPD: Я думаю в этом и прелесть PR, что при должном внимании - (почти) каждый может внести свой вклад и видение в заложенную автором идею

akaia-shadowfox · 2021-04-05T18:50:46Z

@martis-git я хотела переименовать ветку чтобы привести её к формату, но из-за этого закроется PR. Как поступить?
По самому формату: не уверена что "docs" вообще нужен в названии веток, потому что весь репо про документацию, то есть контекст и так указан

akaia-shadowfox · 2021-04-05T19:03:51Z

С форматом комментариев к коммитам и заголовков PR: тоже не уверена, что нужно указывать "docs"
Я бы предложила подобный формат:
basics(philosophy): Fix typo
abstractions(domain): Add basic description
domains(shared): Add lorem ipsum dolor sit amet
domains(shared): Fix description of foobar

Эти правила как раз можно описать в contribution guide

azinit · 2021-04-05T21:57:12Z

@karina-drummer
С форматом комментариев к коммитам и заголовков PR: тоже не уверена, что нужно указывать "docs"
Я бы предложила подобный формат:

Упомянул твое мнение в #81 , можем там потом продолжить дискуссию (либо отдельно)

Но как по мне - оверхедно)

Я еще понимаю такое:

feat(domains)
fix(concepts)

Но когда мы и "тип коммита" подстраиваем под методологию... Ну уж извини, мне лично кажется, что это больше про скоуп, а не про тип коммита)

azinit · 2021-04-05T22:01:05Z

@karina-drummer
я хотела переименовать ветку чтобы привести её к формату, но из-за этого закроется PR. Как поступить?
По самому формату: не уверена что "docs" вообще нужен в названии веток, потому что весь репо про документацию, то есть контекст и так указан

Оставь как есть пока. То что про нейминг веток писал - это "на потом"
Касаемо формата - возможно ты и права, но откуда мы можем быть уверены, что потом не появится какая-нибудь кодогенерация и в целом работа с кодом при работе с докой? (что как раз скорее будет соответственно feature/bugfix/refactor)

Или вот еще задача-баг (#67) - я бы для такой задачи например завел ветку формата bugfix/**, поэтому думаю указывать лишний раз docs - не особо страшно

akaia-shadowfox · 2021-04-08T18:43:12Z

@martis-git кстати, about в структуре каталогов ещё более странно смотрится, потому что, опять же, вся документация и есть about

azinit · 2021-04-08T19:23:50Z

@karina-drummer
кстати, about в структуре каталогов ещё более странно смотрится, потому что, опять же, вся документация и есть about

Ну никто и не говорил, что это окончательный вариант)

Если есть предложения - велком в ишью

А вообще - хотелось там держать что-то вроде "мета-инфы" о самой методологии (т.е. не ее содержание, а что-то абстрактное, предметное, то что "над методологией" - т.е. как раз ее цели ,видение и т.д.)

akaia-shadowfox · 2021-04-19T12:28:10Z

Included in #98

Karina Drummer added 3 commits March 21, 2021 18:19

Add .gitignore

14469a4

docs(shared): Add basic definition

72a5e55

docs(shared): Add subdirectories placeholders

0e65ebd

akaia-shadowfox requested a review from a team March 21, 2021 22:28

akaia-shadowfox self-assigned this Mar 21, 2021

akaia-shadowfox requested review from niyazm524 and sergeysova and removed request for a team March 21, 2021 22:28

akaia-shadowfox linked an issue Mar 21, 2021 that may be closed by this pull request

COMPLETENESS: Доработать статью про shared #70

Closed

akaia-shadowfox added this to the 2.0.0-alpha.1 milestone Mar 21, 2021

akaia-shadowfox added the documentation label Mar 21, 2021

docs(shared): Add spelling amendmends

171919e

azinit suggested changes Mar 22, 2021

View reviewed changes

docs(shared): Add additional linebreaks & Update h1

feae35f

azinit added the help wanted Extra attention is needed label Mar 25, 2021

akaia-shadowfox changed the title ~~docs(shared): Add namespace~~ docs(abstractions): Add shared domain Apr 5, 2021

azinit removed this from the Спринт 2021_1 milestone Apr 5, 2021

azinit mentioned this pull request Apr 5, 2021

CONTRIB: Выработать и описать внутренний воркфлоу #81

Closed

azinit added this to the Спринт 2021_2 milestone Apr 6, 2021

sergeysova removed the request for review from niyazm524 April 10, 2021 08:18

sergeysova requested review from AlexandrHoroshih, azinit, binjospookie and ilyaagarkov April 10, 2021 08:18

azinit removed the help wanted Extra attention is needed label Apr 11, 2021

akaia-shadowfox changed the title ~~docs(abstractions): Add shared domain~~ feat(layers): Add basic definition of shared Apr 19, 2021

akaia-shadowfox removed request for AlexandrHoroshih, azinit, binjospookie, ilyaagarkov and sergeysova April 19, 2021 08:56

akaia-shadowfox closed this Apr 19, 2021

akaia-shadowfox deleted the mar-2021-add-shared branch April 19, 2021 12:28

feat(layers): Add basic definition of shared #79

feat(layers): Add basic definition of shared #79

Uh oh!

Conversation

akaia-shadowfox commented Mar 21, 2021

Uh oh!

azinit commented Mar 22, 2021

Uh oh!

azinit commented Mar 22, 2021

Uh oh!

azinit left a comment

Choose a reason for hiding this comment

Что не так?

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

akaia-shadowfox Mar 22, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

azinit Mar 25, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

azinit Mar 25, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

azinit Mar 25, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

akaia-shadowfox Apr 4, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

akaia-shadowfox Apr 4, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

azinit commented Mar 22, 2021

Uh oh!

azinit commented Mar 22, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Если же отвечать на твой основной месседж...

TL;DR: Дерзай как знаешь и считаешь нужным, но вроде как договаривались всю информативную часть из дискуссии в доки переносить

Uh oh!

akaia-shadowfox commented Apr 5, 2021

Uh oh!

akaia-shadowfox commented Apr 5, 2021

Uh oh!

azinit commented Apr 5, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

feat(layers): Add basic definition of `shared` #79

feat(layers): Add basic definition of `shared` #79

akaia-shadowfox Mar 22, 2021 •

edited

Loading

azinit Mar 25, 2021 •

edited

Loading

azinit Mar 25, 2021 •

edited

Loading

azinit Mar 25, 2021 •

edited

Loading

akaia-shadowfox Apr 4, 2021 •

edited

Loading

akaia-shadowfox Apr 4, 2021 •

edited

Loading

azinit commented Mar 22, 2021 •

edited

Loading

`TL;DR:` Дерзай как знаешь и считаешь нужным, но вроде как договаривались всю информативную часть из дискуссии в доки переносить

azinit commented Apr 5, 2021 •

edited

Loading