Эта статья была впервые опубликована в публичном аккаунте vivo Internet Technology WeChat.
Ссылка на сайт:https://mp.weixin.qq.com/s/VWjB83NBTg6FwPBDg8G0HQ
Автор: Ши Чжэнсин
В этой статье обобщается опыт большого количества ежедневных консультаций, встречающихся в моей работе, и объясняется, что должно быть написано в документе фреймворка разработки. отфункциональная основа,Процесс использования функций,Описание функцииТри измерения описывают логику написания документа. Я надеюсь вдохновить своих коллег, которые также занимаются разработкой и поддержкой сред разработки.
Введение
За короткий период времени я взял на себя ежедневное сопровождение более 10 фреймворков разработки, большинство из которых все еще находятся в активной итерации разработки. В среднем за это время один день в неделю может быть прерван работой внутреннего ПО для обмена мгновенными сообщениями, так что невозможно войти в установленные рабочие задачи.Когда встречаются три-два, это очень сложно, и очень вовремя -потребление для расследования.Или, когда есть проблема, выход за эту неделю будет ниже.
Некоторые люди скажут, разве вы не можете сосредоточиться на ответах на запросы пользователей? Ответ лучше не делать, потому что мы ставим удовлетворенность пользователей на очень важное место, и своевременность ответов, несомненно, окажет важное влияние на удовлетворенность пользователей.
После обобщения проблемы и ее классификации:
(1) На первую категорию приходится около 40% ежедневной поддержки., о том, как использовать этот фреймворк разработки в конкретном сценарии (поскольку структура документа пользователя сбивает с толку при взятии на себя обслуживания, сложно быстро найти нужный контент в документе или такого контента нет вообще, пользователь можно только позвонить для консультации или собеседования);
(2) Вторая категория, на которую приходится около 30%, — это непредвиденные ситуации во время использования.Если вам нужна помощь в поиске и устранении проблемы;
После многократных размышлений и обобщений я думаю, что есть много возможностей для оптимизации. После оптимизации документа в соответствии с моими идеями предполагается, что это может сэкономить мне почти 1 день времени в неделю. Далее я представлю свои идеи. и практический опыт.
2. Определение проблемы и мое мышление
1, описание проблемы
Ниже я привожу идеальное состояние (слева) и реалистичное состояние (справа), отношения между документом, разработчиком фрейма и пользователями фреймворка.
Как видно из рисунка, в идеальном состоянии разработчикам нужно только передавать информацию пользователям через документы.На самом деле многие фреймворки с открытым исходным кодом используются таким же образом, хотя у пользователей остаются каналы для общения с разработчиками (такие как проблема с электронной почтой или github), но это низкая частота. В реальности основной фреймворк разработки внутри крупной компании требует не только написания документов, но и постоянного общения с внутренними пользователями в различных видах и каналах.
Чтобы дать всем общее представление о том, что это за общение и с какими проблемами документации я сталкиваюсь, здесь я внесу некоторые модификации в реальные кейсы в прошлом — чтобы добиться меньшего количества случаев и абстрагировать больше проблем — следующим образом.
1.1 Случай 1
Старый сотрудник хочет использовать каркас автоматического выключателя для защиты своей системы. Он нашел ссылку на документ каркаса автоматического выключателя по ссылке на домашней вики-странице нашей команды, сохраненной им самим. Потратив 15 минут на внимательное чтение всех документов, он не уверен, почему он должен использовать нас.Структура прерывателя цепи, предоставленная командой, вместо того, чтобы использовать открытый исходный код напрямую, он не особо думал об этом, он написал демонстрацию непосредственно в соответствии с описанием документа, и, наконец, она заработала;
Затем он приготовился официально применить его к бизнес-коду.Из документа он узнал, что ему может потребоваться настроить некоторые параметры инициализации в соответствии с его бизнес-ситуацией, но поскольку описание параметров очень простое, он никогда раньше не использовал структуру fuse, а знание предметной области высокопрофессиональное.После прочтения он в принципе не понял какого эффекта это может дать,поэтому он собирался звонить за консультацией.Так он увидел что создатель документа и человек который недавно его модифицировал не тот же человек.Поколебавшись, он позвонил тому, кто изменился последним.
1.2, дело
Одноклассник в Нанкине имеет опыт разработки Java, который взял на себя задачу разработки с большими данными; в связи с предыдущим участием в обучении скаффолдингу на основе SPIRNG BOOT (далее скаффолдинг), найдите наш сайт проекта с PPT И скачайте проект, попробуйте выполнить поиск в Wiki, найдите наш документ «Использовать быструю интеграцию Scaffolding Vivo-mybatis» или нет, не уверен, что его библиотека поддерживает сцену с несколькими таблицами, одну библиотеку, поэтому он позвонил, чтобы прийти; проконсультируйтесь с подтверждение поддержки и понимание разницы в конфигурации между одной библиотекой с несколькими таблицами и несколькими таблицами, а также подключаемый модуль таблицы оценки ветвей в mybatis, но в документе нет введения.Принцип библиотеки, нет примера конфигурации единая библиотека многотабличная, несколько раз пытался сделать, и наконец, после доработки фреймворка четко настроил конфигурацию, проблема решена, но стоит больших сил. .
1.3 Случай 3
Коллега нашел на вики 2 документа о доступе проекта spring boot к центру конфигурации vivo.Они редактировались и поддерживались разными людьми.Я не знал какой документ использовать,поэтому позвонил в один из них,чтобы сообщить о проблеме ситуация. Авторы последних двух документов подтвердили, что ситуация верна и их необходимо объединить, но трудно решить, следует ли помещать объединенные документы в каталог пользовательских документов центра конфигурации или в каталог пользовательских документов скаффолдинга.
2. Краткое описание проблемы
2.1. Идентификация проблемы в случае 1
Вопрос 1:Вход в документы нужен из уст в уста; Если вы не сохраните информацию о ссылке, то от другого коллеги спросили.
Вопрос 2:В содержании документов есть пробелы, и пользователи могут прочитать все документы в короткие сроки, и они не классифицируются в соответствии с их функциональными характеристиками, поэтому им нужно прочитать все документы.
Вопрос 3:Нет конкурентного анализа, и нет четкого представления о разнице между внутренней структурой и структурой с открытым исходным кодом.
Вопрос 4:Описание параметров конфигурации фреймворка слишком простое, и нет соответствующего введения в предметную область, и пользователь не может его понять или понять.
Вопрос 5:Базовая структура, поддерживаемая на основе открытого исходного кода, не настраивается и не оптимизируется в соответствии со средой разработки компании, и параметры необходимо настроить, прежде чем ее можно будет использовать в Интернете.
Вопрос 6:Текущий владелец фреймворка не ясен с точки зрения пользователя.
2.2. Идентификация проблемы в случае 2
Вопрос 1:Адрес сайта проекта нужно запоминать людям отдельно, и его крайне сложно опубликовать.
Вопрос 2:Базовый документ не позволяет легко получить его, требуя от пользователей поиска неопределенности.
Вопрос 3:Пользователю необходимо позвонить, чтобы узнать, поддерживается ли его сценарий, указав, что в данном документе нет точного описания поддерживаемых сценариев, есть упущения и не приведены демонстрационные примеры в соответствующих сценариях.
Вопрос 4:Когда фреймворк упакован, нет пакета с исходным кодом.
Вопрос 5:Отсутствие документации описывает реализацию принципа.
2.3 Идентификация проблемы в случае III
Вопрос 1: несколько документов говорят об одном, что указывает на то, что в документе есть путаница.
Вопрос 2:Трудно прийти к соглашению о том, к какому модулю относится документ, что указывает на то, что обязанности не распределяются с точки зрения пользователя.
3. Что должно быть написано в рамочном документе
1, окраина
В этой статье До сих пор вопрос о документе описывал эти проблемы, а также то, по какому сценарию они возникли прямо перед вами. Но прежде чем мы напишем документ, вы должны сначала иметь стандарт, чтобы определить, насколько документ считается хорошей документацией о нем? Я думаю, что ответ очень прост, то есть до тех пор, пока сокращается общение между пользователями и разработчиками, до тех пор, пока повышается эффективность общения, бесконечно близкое к идеальному состоянию, показанному на диаграмме, тогда даже если пользовательская документация этой структуры является хорошей документ. Так что документ тоже используется для решения проблемы, его можно рассматривать как отдельный продукт. Этот документ что писать, то что продукт должен функционировать.
Далее разберем ключевые особенности документного продукта:
- Основные пользователи:пользователи фреймов;
- Жесткие требования:Справка на основе документации для быстрого и удобного использования фреймворка;
- Типичный сценарий:Прочитав документ кадра, полный доступ, использование, настройку, устранение неполадок и другие ежедневные процессы разработки;
- Концепция продукта:Избегайте или сокращайте частое прямое общение между пользователями фреймворка и разработчиками и повышайте эффективность общения, каким бы плохим оно ни было, чтобы пользователи могли использовать его более плавно, освобождая разработчиков от ежедневной поддержки;
- Конкурентное исследование:Пользовательская документация для dubbo и spring может быть исследована
2. Что должен содержать документ?
Основываясь на своем собственном прошлом опыте и в сочетании с приведенным выше анализом ключевых функций продукта, я считаю, что полный рамочный документ должен включать следующие категории.
- Предыстория и знания предметной области (представить предысторию, основные принципы, знания предметной области, имена собственные и попытаться поднять уровень знаний некоторых пользователей до уровня разработчиков)
- Применимые сценарии, а также зависимости и ограничения, соответствующие сценариям
- Доступ, использование и настройка, связанные с
- Информация о качестве (функциональное тестирование, тестирование производительности, безопасность)
- Развитие привычек пользователей (предложения, обмен знаниями, меры предосторожности)
- Руководство по проектированию архитектуры и чтению исходного кода
Поскольку важность каждой части документа разных фреймворков будет разной, длина описания, способ представления и носитель контента вышеуказанных категорий будут очень разными.На следующем рисунке показан фреймворк распределенной блокировки, разработанный нашей командой на основе способ представления вики Каталог документации. Серийный номер впереди предназначен для облегчения общения с пользователями на основе документов (прямое общение с пользователями неизбежно).
3. Уточнение посадки
После прочтения приведенного выше примера изображения понимание станет немного более интуитивным.Далее я уточню приведенные выше 6 более абстрактных классификаций на конкретных страницах функций вики.Конечно, это всего лишь пример:
(1) Домашняя страница фрейма: Дайте обзор текущего фреймворка, например, пропагандистский лозунг, его функциональные особенности, проблемы, которые он может решить, и сценарии использования; руководство по следующим шагам, руководство сообщества; если он разработан на основе версии с открытым исходным кодом, он также может быть представлен здесь на основе версии с открытым исходным кодом Что он сделал Если нет, то лучше сравнить его с аналогичными продуктами с открытым исходным кодом (анализ конкурентного продукта), также могут быть основные показатели, чтобы показать конкурентоспособность и популярность, и улучшить уверенность пользователей в их использовании.
(2) Знание предметной области:Цель состоит в том, чтобы приблизить соответствующий уровень знаний пользователей к вашему, позволить пользователям понять ваше поведение и методы, а также повысить узнаваемость или удовлетворенность пользователей.
(3) Быстрый старт:Есть только описания быстрого доступа и использования простых сценариев с минимальными зависимостями.Пользователи могут напрямую запустить приведенный выше код, скопировав его, и описать, как его получить. Демонстрационный метод примера также должен быть приведен здесь.
(4) Зависимости и ограничения:Опишите зависимости текущей работы фреймворка, включая зависимости операционной среды, от которых должен зависеть maven, и выберите список зависимостей (например, dubbo использует zookeeper и nacos, поскольку зависимости реестра разные), зависимое промежуточное ПО или бизнес-системы; информация об ограничениях, например невозможность использовать fastjson в качестве инструмента json, вы должны использовать кластер Redis в режиме кластера и т. д.
(5) Элементы конфигурации:Подробно опишите, как используется каждая конфигурация, что она делает, меры предосторожности, а ключ конфигурации должен иметь определенную логику проектирования для легкого понимания.
(6) Подробные инструкции по применению:Комплексная пользовательская документация для того, как использовать все характеристики емкости, описанное описание, описание всех деталей.
(7) Примеры использования в нескольких сценариях:Исходя из различных сценариев использования пользователей, предоставляется код конфигурации/образца, а также предоставляется демонстрация, которую можно загрузить и импортировать в IDE, что удобно для чтения пользователями с различными потребностями.
(8) Запись о выпуске версии:Он используется для отслеживания и записи времени выпуска и изменений версии.
(9) Руководство по обновлению:Как направить пользователей на обновление версии.
(10) Конструкция и принцип:Содержит различные типы проектной документации, описания принципов и руководства по исходному коду. Помогите опытным пользователям понять принцип работы и предоставьте определенные рекомендации по чтению исходного кода; также необходимо объяснить, какие спецификации соблюдаются при разработке, чтобы помочь пользователям определить основные функции.
(11) Информация о качестве:Отчеты о функциональных испытаниях, отчеты о тестировании производительности, отчеты о сканировании уязвимостей и стандартизированные спецификации.
(12) Часто задаваемые вопросы:На этой странице вы можете обобщить и систематизировать более типичные/распространенные вопросы пользователей, чтобы другие коллеги, у которых есть похожие вопросы, могли их видеть (аналогично рекомендациям) и уменьшить нагрузку на общение. Следует отметить, что это всего лишь временное публичное руководство по вопросам.В долгосрочной перспективе вопросы, часто задаваемые пользователями, должны быть оптимизированы на уровне проектирования системы или должны быть существенно подсказаны в подробных инструкциях по использованию.
В-четвертых, как написать рамочный документ
Читатель документа, как правило, программисты, и способность программиста - это сильна, поэтому документ, который мы написал, сильно логично, является основным требованием, а следующие три размера описывают логику документа.
1. Логика функциональной структуры
Общую логику документа рекомендуется излагать в стиле «общая оценка — общая сумма» на основе шести вышеуказанных категорий. В первую очередь нам необходимо представить фреймворк в целом, который можно разместить на домашней странице фреймворка, а затем указать категорию выводимого документа (в разных фреймворках может быть соответствующая категория документов). быть выборочно написанным, конечно, не обязательно выводить все 6 категорий документов) и Перечислить особенности фреймворка, что является процессом "общей оценки". Документация для одной категории или документация для одной функции может быть указана как отдельный модуль. Кроме того, части, которые пользователи часто просматривают, также должны быть добавлены в меню и написаны отдельно, что пользователям удобно для быстрого чтения, поиска и просмотра. Давайте взглянем на домашнюю страницу документации распределенной блокировки:
При написании документа одной категории его также необходимо многократно разбивать по форме «общий балл» в зависимости от сложности конкретного содержания. После нескольких разделений обычно требуется «общий» процесс для объединения в полную функциональную функцию.
В каталоге документов распределенной структуры блокировки на рисунке 2, с логической точки зрения функциональной структуры, несмотря на то, что содержание «зависимости и ограничения» будет относительно небольшим, обычно его необходимо просмотреть при использовании структуры, поэтому он используется здесь как независимый модуль. «Быстрый старт», как следует из названия, должен помочь пользователям быстро понять структуру. Это очень важно. Обратите внимание на самые простые слова, самую простую конфигурацию, наименьшее количество кода, наименьшее количество зависимостей и наименьшую длину объяснения. , Цель состоит в том, чтобы быть в состоянии понять. Конечно, «Руководство по настройке» относится ко всем перечисленным конфигурациям фреймворка, включая параметры настройки функций и производительности, и следует уделить внимание отделению часто используемых конфигураций от тех, которые обычно не используются. «Подробное описание» в основном содержит исчерпывающее описание платформы с точки зрения доступа пользователей, использования, настройки и мер предосторожности и обычно занимает больше всего места. «Демонстрационный пример с несколькими сценами» рекомендуется для перечисления всех сценариев использования пользователя и предоставления примеров кода для сценариев. «Версия и обновление» на самом деле представляет собой журнал выпусков и изменений, инструкции по совместимости версий и соответствующие меры предосторожности для пользователей при обновлении.
Ниже приведен каталог страницы «подробного описания» распределенной структуры блокировки, разработанной нашей командой:
2, функция логики потока
2.1 Использование функций
Логику потока функций можно понимать как объединение нескольких определенных шагов при использовании функции. Например, типичные шаги для использования инфраструктуры распределенной блокировки следующие:
Положитесь на пакет jar распределенной структуры блокировки через maven -> настроить адрес zookeeper или redis -> код (получить блокировку) -> код (освободить блокировку)
Как вы думаете, этот процесс написан так, что все его очень хорошо понимают или не очень хорошо понимают? Хотя общий процесс очень прост, документация не должна просто записывать это содержимое, иначе это приведет к бесконечному общению пользователей с разработчиками. Например, документ также должен включать: указать минимальную версию функции (от какой версии пакета следует зависеть), как зависеть от среды Spring, среды загрузки Spring и чистой среды Java, область применения зависимые трехсторонние конфликты пакетов и методы устранения неполадок, параметры конфигурации zookeeper и доступность кластера. Описание стабильности платформы, описание управления соединениями zookeeper, описание повторного входа в процесс получения и освобождения блокировки, руководство по обработке исключений, лучшие практики и т. д. Это все еще самый простой способ использования API. Более подробная информация объяснена. Что касается того, какие детали должны быть прописаны четко, то это можно постепенно улучшать, и документ тоже нужно итеративно обновлять.
Для удобства пользователя рекомендуется описывать сценарии использования последовательно в виде блок-схем. Соответствующие детали должны быть четко объяснены на каждом этапе, чтобы избежать телефонной связи и подтверждения процесса использования пользователем.
2.2 Объяснение принципов и источника
При описании принципа фреймворка или исходного кода часто используются описания изменений состояния, описания жизненного цикла и т. д. Очевидно, что обычных блок-схем недостаточно для четкого выражения, в настоящее время их заменяют диаграммы переходов состояний, диаграммы последовательности и добавлены процессы с плавательными дорожками.картинка, эффект будет лучше. Давайте взглянем на диаграмму перехода состояния жизненного цикла TCP-соединения:
3. Логика функционального описания
В функциональной логике процесса написано, что для каждого шага процесса должны быть четко прописаны и улучшены соответствующие детали за счет постоянного обновления и итерации документа. Как упорядоченно и полно описать эти детали здесь, нужно обратить внимание на следующие моменты:
- все:Перечислите все возможные пункты и объясните их один за другим без пропусков;
- Учитывайте все точки воздействия:Например, изменение конфигурации функции может повлиять на другие функции; что, если тип возвращаемого параметра резервного метода, упомянутого в структуре распределенной блокировки, несовместим с типом возвращаемого параметра обычного бизнес-метода? Не позволяйте пользователям спрашивать вас;
- Условие суждения ясно:Например, когда какие условия будут выполнены, какая логика будет запущена, вы можете использовать if/else/while для написания псевдокода;
- Смысл ясен:То, что вы видите, это то, что вы получаете, и слова строги, чтобы выразить смысл без двусмысленности;
- Повествовательный фон:Если функция не реализована оптимальным образом или отличается от решения с открытым исходным кодом, лучше предоставить контекст, чтобы пользователи могли вас понять.
V. Резюме
Наконец, мы должны понимать, что образ мышления, логические привычки у всех разные, независимо от того, сколько мыслей и написания документов, трудно сделать полную десятку красоты и никакой небрежности, поэтому есть также канал обратной связи с пользователем, такой как большинство системы документов Имеют функцию комментариев. На следующем рисунке зрелость документа связывает пользователя и разработчика.
Основная цель написания документа — помочь пользователям использовать фреймворк, но нельзя игнорировать тот факт, что разработчики фреймворка также являются важными пользователями документа, который удобен как для пользователя, так и для них самих.
Эта статья наводит на размышления о проблемах, существующих в ежедневном консультировании, и думает, что документ также является продуктом, который используется для решения проблем определенной группы людей. Поскольку я не знаю продукта, я не могу деконструировать документ с профессиональной точки зрения продукта, я могу только объяснить, что документ должен быть написан, исходя из собственного опыта, и проиллюстрировать логику написания документа из функциональная структура, процесс использования функции и меры предосторожности при описании функции. Я надеюсь вдохновить некоторых коллег, которые также занимаются разработкой и поддержкой сред разработки.
Как разработчику фреймворка, одобрения и лайки пользователей — наша лучшая награда. Мы будем обращать внимание на качество кодирования, но часто игнорируем важность документации.Фреймворк классный, но документация написана плохо, и пользователи не могут использовать его плавно, что сильно снижает ценность фреймворка. Очень важно это осознавать, писать классный код, писать документацию понятно и легко, чтобы пользователи думали, что фреймворк классный, и, кстати, автор думал, что автор классный. Делайте больше потрясающих вещей, и ваше техническое влияние естественным образом возрастет.
Больше контента, пожалуйста, обратите вниманиеживые интернет-технологииПубличный аккаунт WeChat
Примечание. Чтобы перепечатать статью, сначала свяжитесь с учетной записью WeChat:Labs2020соединять.