схема ставит все точки над и. выбирает цели, используемые решения для их достижения и все нюансы по пути к ним
так как мы участники deep, нам стоит объединять усилия, данная схема позволит подойти к написанию документации. стандартизация нужна что бы понимать почему так а не иначе. все смогут видеть картину целиком и помогать в развитии нашего продукта
(кратко говоря, схема это патерн действий для людей которые будут работать с этой документацией, разделяется она на 3 основных этапа: постановка цели, выбор инструментария для выполнения поставленной цели и последний, расстановка промежуточных приоритетов и их выполнение для достижения цели)
наша цель написать документацию по deep, в данный момент тут будет очень упрощённый макет, так как задача это комплексная и требует асинхронного исполнения. посему мы обратим свой взор пока что только на документацию по deep-case
ниже будут поставленные гештальты. то какие надежды и ожидания мы возлагаем на документацию по deep-documentation. проще говоря хотелки к которым мы стремимся
документация как и deep не должна быть набором понятий и возможностей, это целостная взаимосвязанная сеть знаний, где каждое понятие от чего то исходит и к чему то приходит. каждое слово это не что то новое, это связь давно известного старого, что конечно сильно упростит понимание всей картины в целом
каждый блок должен служить своей цели, все что пишется, должно работать на понимание. именно на понимание, а не на передачу информации через текст, вы обязаны объяснить человеку написанное а не просто сказать о существовании возможностей. но во всем должен быть баланс, не изобилуйте информацией мало относящейся к делу
позвольте человеку изучать только полезную для него информацию. основная документация может быть поверхностной. не бойтесь упрощать и описывать не с дотошной точностью, лучше оставьте ссылку на страницу с подробным и понятным разбором темы, к которому можно будет вернутся после понимания того, что сейчас действительно имеет значение
сколько людей на планете, столько и способностей и взглядов. нет не чего плохого в том, что бы заготовить туториалы для разных родов деятельности в deep, даже не смотря на то, что такие документации могут друг друга цитировать. пускай, мы работаем на удобство наших пользователей, пускай они погружаются в возможности нашего инструментария с максимально понятным для них введением
что бы сделать что то, нужно что то использовать. в нашем случае это все то, что может помочь нам в написании документации
асинхронная документация. так как над документацией одновременно может работать не один человек то нужно добиться асинхронности её написания так, что бы это не мешало работе друг друга. я добиваюсь решения этой проблемы благодаря независимым средам в одном проекте. здесь эти среды являются обычными папками
оставьте в корне проекта папку с именем которая будет указывать на вашу причастность и начинайте работать в ней как вам удобно и с теми инструментами что вам нужны. только не забудьте оставить в ней схему того как работать с вашим проектом (если он не соответствует этой схеме), это нужно что бы кто либо мог понять как можно продолжить или исправить вашу работу, помимо того это напоминалка вам самим же, почему вы сделали так а не иначе
стоит упомянуть про контроль версий. это очень плотно переплетёно с git. так как по большей части он задал такое ведение версий и им же мы пользуемся для совместной работы над документацией, а так же пользуемся github как платформой для первичной публикации и распространения. про то, как его использовать вы можете прочитать здесь. помимо этого стоит отметить что заметки так же структурируются благодаря системе названий коммитов
хотя может так не казаться, стандарты тоже своего рода материал готового проекта, все зависит от контекста. в данном случае стандарты позволят нам определится может ли показанная документация быть допущена к релизу или её требуется скрыть до дальнейшей доработки. ниже будет краткое перечисление, но подробнее вы можете прочесть здесь
следующие требования выдвигаются при написании документации:
- синтаксис (#syntax)
- локализация (#localisation)
- работоспособность (#works)
- ассоциативность (#associativ)
- лаконичность (#laconic)
- глубина (#depth)
- ориентированность (#orientation)
- соответствие целям (#relise)
когда мы говорим про полную асинхронность то краеугольным камнем является объединение работ людей. если в случае написания сайта, все понятно, есть база данных, backend и frontend, то в нашем случае есть статьи от разных людей на разные темы. они могут писать свои статьи там, где им удобно, мы же в свою очередь можем использовать их наработки уже в общей, объединеной базе, не ограничивая людей
целью всего этого станет написание основной документации над которой могут так же работать несколько людей, но в данном случае это будет жестко типизированная и прописанная пошагово документация, ставящая конкретные цели и имеющая особенность постоянно дополнятся, обновляться и изменятся. у основной документации будет схема и система заимствования (с указанием источников, дабы люди могли углубится в тему или посмотреть на неё под углом автора)
материалы (статьи других людей), которые мы будем использовать, не всегда будут соответствовать стандартам общей документации, поэтому к этой общности их надо привести, но желательно сохранить то над чем мы работали в первозданном виде и описать что было изменено. для этого будет использоваться механика заголовков. просто напишите первую неизменную версию, добавьте теги того, какие стандарты были соблюдены в данной итерации и добавьте новый заголовок выше (чем выше, тем новее) и сделайте новую итерацию более подходящую для стандартов
тот самый инструмент позволяющий достигнуть цели. я перепробовал много подходов и по итогу понял, что этот самый подходящий и простой в использовании, просто перечисляешь все что взбредёт в голову, что может помочь в написании и выбираешь наиболее полезные и важные в данный момент и начинаешь работать, в то же время документируя свою деятельность. это полезно и универсально. с заметками этой схемы вы можете ознакомится здесь