Перенести /docs в /wiki GitHub'a

[baileys-li]

У GitHub есть функциональность wiki-страниц в репозитории. Судя по их описанию, оно подходит как замена папки /docs:

You can use your repository's wiki to share long-form content about your project, such as how to use it, how you designed it, or its core principles. A README file quickly tells what your project can do, while you can use a wiki to provide additional documentation.

Тогда каждому контрибьютору не нужно будет хранить документы в своём локальном форке. И если нужно будет редактировать эти документы, он сможет сделать это отдельно. Также можно будет клонировать wiki-репозиторий отдельно, если потребуется работать офлайн (редкий кейс).

[solarrust]

Строго имхо: я бы оставила все инструкции внутри репозитория. Мой личный частый сценарий: надо подсмотреть правило оформления текста или меты в материалах. Сейчас мне достаточно в этом же репо локально открыть папку и подглядеть. При новой структуре нужно будет открывать браузер, там гитхаб, там репо с вики, там искать нужный док.

Кажется, проблема хранения доков локально не очень острая. Их не много и весят они мало. При этом всегда под рукой.

Буду рада почитать другие мнения!

[Inventoris]

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

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

[vitya-ne]

В принципе можно и продублировать.
...
С другой стороны, можно сделать для репозитория краткую выжимку самого необходимого при написании материала. Набор шпаргалок. А в Wiki оставить полный вариант.

Или наоборот: иметь вики страницы, полные ссылок на файлы документации, лежащей в репо.
Таким образом сам контент документации, по-прежнему остаётся частью репозитория, но и страница wiki есть, для доп. навигации.

[baileys-li]

Правда в таком варианте придётся двойную работу делать

Можно попрбовать сделать git sub module. Нужно потестить

[alexeyten]

не, submodule это ужас-ужас.

Я б скорее предложил github pages из папки /docs сделать.

Но вообще проблема кажется несуществующей

lynn@lynn-nix:~/p/doka-guide-content$ du -sh */ | sort -h
8,0K	settings/
28K	specials/
64K	pages/
1,3M	interviews/
1,8M	docs/
15M	recipes/
16M	a11y/
22M	js/
24M	people/
25M	css/
26M	tools/
126M	html/

[igsekor]

Как ты мы забыли рассказать, а почему было принято именно такое решение. Документация внутри репозитория задумывалась не просто так. Из числа аргументов в пользу существующего решения:

• привычно для опенсоурс проектов (Вики чаще используется для решений, где есть пользователи, которым необязательно уметь пользоваться Git'ом. У нас получается есть определённый порог входа — умение им пользоваться)
• всегда под рукой через интерфейс GitHub'а или в локальной копии
• максимальная доступность через веб-интерфейс и через редактор кода (и там, и там есть встроенные инструменты для превью, не надо ничего специально собирать не надо)
• иметь одну ссылку на всё, что касается контента Доки
• не распылять ресурсы по поддержке и для удобства (всё, что есть, есть только в одном месте — единственный источник правда, как валидация форм на бэкенде)
• возможность понять, как менялась документация вместе с развитием репозитория, и почему она менялась (на основе коммитов)
• ...

Теперь про преимущества Вики:

• отдельная вкладка на GitHub
• возможность редактирования без Git
• поиск
• :( больше не знаю, может быть есть ещё...

Возможное решение: сделать специальный поддомен, где собрать нашу документацию как отдельный сайт с навигацией и поиском. В этом случае будет только две фичи — наш неповторимый дизайн и поиск. Всё остальное не сильно будет отличаться от существующего решения или решения с Вики, но будет требовать отдельной поддержки. Пока присоединяюсь к строгому ИМХО @solarrust

[igsekor]

А ещё не понятно, а какие преимущества даст нам Вики. В чём задача? А то мы пытаемся решить задачу, но даже не понимаем какую вроде бы... Интересны мнения и правда!