Как открыть техническую документацию

Где хранить техническую документацию продукта

Взгляд дизайнера

Кто мы?

Команда один из продуктов Иксоллы, Чат-платформа. Короче говоря, мы помогаем соединять людей. Пользователь, у которого проблемы с оплатой, пишет в поддержку. Разработчик игры свяжется с менеджером аккаунта с вопросами. Наша команда предоставляет средства коммуникации для всех участников диалога.

Чат-платформа — сложный продукт с большим количеством проектов. Помимо основного продукта, Xsolla Chat, у нас есть виджет для работы с пользователями, бот для сортировки запросов, сервис для работы с интеграцией сторонних мессенджеров и большие планы по реорганизации и оптимизации всего этого счастья.

Мы стараемся решать задачи DevOps сами, поэтому у нас есть все конфигурации CI/CD и Kubernetes для внесения изменений.

Как не заблудиться?

Чтобы не заблудиться запутавшись в этом зоопарке проектов и технологий, наша команда старается вести документацию. В компании стандартом является Confluence, и в какой-то момент стало ясно, что мы из него выросли.

Недостатки Confluence

  • Много путаницы в результатах спринта, протоколы совещаний и другая «управленческая» информация.
  • Плохая реализация пробелов и поиска. Чтобы найти интересующую вас информацию, особенно если вы не помните точную строку, вам придется выполнить довольно тяжелый поиск.
  • Невозможно описать API или нарисовать UML-диаграмму

Что делать?

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

  • Удобство содержания и навигации
  • Синхронизация данных
  • Совместимость с UML (PlantUML, Mermaid)
  • Вариант встраивания API (Swagger, открытый API)
  • Вариант полного или частичного экспорта (PDF)
  • Стоимость

Могу ли я увидеть все ?

Google Docs, One Note, Notion, Evernote и т. д.

У этих продуктов есть одна общая черта: они хороши только для написания статей. У них есть удобный редактор, встраивание изображений и множество замечательных функций. Когда дело доходит до технической стороны, начинаются проблемы.

GitBook

Самый кастомизированный продукт для технической документации, полнофункциональный проприетарный редактор, синхронизация с GitHub, API push, примеры кода. Никаких UML-диаграмм. Платно.

Archibee

Повторяет функционал Notion, при этом есть возможность вставки API, кода, UML. Платный и имеет раздражающую функцию зависания через некоторое время.

Docsify.js

Бесплатный, легкий и с множеством плагинов. Нет редактора, но есть поддержка Markdown. Диаграммы UML, Swagger через плагин. Полная настройка заняла 2 часа.

Документ

Похож на Docsify.js, удобная базовая настройка, сборка через Webpack.

Орхидея

Похоже на описание чтобы было хорошо, но написано на Java, что вызывает вопросы по поддержке. Не удалось запустить панель администратора демо-страницы.

А также

Финальная таблица не попала Еще около 15 инструментов не соответствуют 2 или более требованиям

Источник

Технические документация по разработке программного обеспечения: кто, почему, когда и как описывает проект

¡ Здравствуйте! Меня зовут Даша Григорьева, я технический писатель в 65apps. Мы разрабатываем комплексные мобильные решения и моя задача подготовить техническую документацию для проектов. Роль технического писателя очень часто недооценивают в компании (не здесь, конечно). По этой причине я хочу рассказать вам, зачем девелоперской компании нужен такой специалист, что такое техническое задание, чем оно отличается от технического задания и зачем все это нужно для разработки мобильного приложения.

Читайте также:  Как открыть самим лифт

Поскольку я взаимодействую со многими компаниями, я по-прежнему твердо верю, что написание спецификации для разработки программного обеспечения — пустая трата времени и денег. В 65 Apps мы думаем иначе. Поэтому приведу несколько аргументов в пользу технической документации и расскажу, чей тип и как.

Техническая документация позволяет оценить затраты на разработку и согласовать функционал будущей системы. Если возникают споры о цене и сроках разработки той или иной фичи, она может стать своеобразной гарантией для заказчика. С другой стороны, если приложение необходимо разработать, документация облегчит процесс разработки и даст четкое представление о том, можно ли интегрировать новую функциональность в существующую систему.

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

Задание и техническое задание — это два разных документа. Техническое задание отвечает на вопрос «что нужно сделать? В начале проекта они составляются аналитиком. Технический проект разрабатывается техническим писателем. Этот документ создается после ТЗ и отвечает на вопрос «как это сделать?».

Кто пишет техническую документацию

ТЗ обычно разрабатывает аналитик. Он тот, кто общается с клиентом/потенциальным клиентом и определяет его требования. В сложных случаях к процессу могут привлекаться руководитель проекта, разработчики, тестировщики и другие специалисты. Чем сложнее проект, тем больше требований к документации. Серьезным клиентам крупных корпораций и государственного сектора требуется разработка документации по ГОСТу, а это очень трудоемкая задача, требующая внимания к деталям и постоянного вовлечения в процесс. И это не только техническое задание, но и технический проект, в котором полностью описаны все решения, подходы и методологии. На него также распространяется ГОСТ. Подготовкой такой документации должен заниматься специалист, технический писатель.

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

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

Что такое технический писатель?

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

Для этого он собирает информацию и материалы от участников проекта и документирует эти данные в соответствии с требованиями заказчика, в том числе из по ГОСТу. Речь идет о ГОСТ 19 «Единая система программной документации» и ГОСТ 34 «Информационные технологии». Набор стандартов для автоматизированных систем». Технический писатель также поддерживает актуальность технической информации по мере необходимости в крупных и сложных проектах.

Какая техническая документация нужна разработчику?

Рассмотрим процесс разработки системы, идеальный с точки зрения ГОСТ
Все начинается с требований заказчика или заинтересованных лиц, которые должны быть идентифицированы и должны быть зарегистрированы в документе «Техническое задание».

Читайте также:  Как открыть свою автоцентр

Техническое задание — это документ, в котором излагаются коммерческие цели, общее описание системы, объем работ, ограничения проекта и разработка, оценка и принятие. Этот документ отвечает на вопрос «что нужно сделать?» и фактически является выражением проблемы.

Аналитик пишет ТЗ и согласовывает его со всеми заинтересованными сторонами. После того, как все требования собраны и утверждены, можно приступать к прототипированию будущей системы и разработке ПО.

На этом этапе начинается разработка дизайнов, сценариев, архитектуры и т. д. Поскольку речь идет о процесса разработки референса, то все это должно быть описано в техническом задании, где также используется некоторая информация из ТЗ. и технические приемы, используемые для создания системы. Например, техническое задание включает дизайны интерфейсов, описание протоколов интеграции с сопутствующими системами и устройствами, пользовательские сценарии, описание алгоритма и его создания, структуру серверов и баз данных, а также другие требования к системе и ее взаимодействиям с другие внешние системы.
и это еще не все: стандартов написания технической документации много, и в каждой стране свои. В национальных стандартах существует отдельный ГОСТ на создание автоматизированной работы и на программный продукт. Например, техническое задание по ГОСТ 19 «Единая система программной документации» может включать следующий перечень работ:

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

В итоге техническое задание отвечает на вопрос «как?» именно этим занимается технический писатель.

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

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

Когда писать техническую документацию

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

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

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

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

Источник

Как «убрать» документацию поставщика

Как «убрать» техническую документацию поставщиков

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

Читайте также:  Как открыть стиральную машинку если она не открывается после стирки индезит
  • доставка и подписание счетов-фактур и иных документов, подтверждающих факт доставки;
  • оплата (аванс или при доставке).
  • Часто в срочных случаях принять товар или материал или оборудование, необходимые для производства, покупатель принимает поставку товара и «закрывает глаза» на то, что необходимая документация не предоставлена, доверяя обещанию поставщика предоставить ее позже. Нередки ситуации, когда технические документы не предоставляются. Как повлиять на недобросовестного поставщика? Ведь если речь идет об оборудовании, например, то должен быть технический паспорт.

    Отказ от оплаты: риск санкций

    Первое, что приходит на ум — Не оплата и договор до получения документов. Последствия для недобросовестных поставщиков изложены в статье 464 ГК РФ.

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

    Данный отказ подпадает под действие статьи 309 ГК РФ, в которой говорится, что обязательства обеих сторон должно быть выполнено. должным образом выполнено. Отказ от исполнения не допускается.

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

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

    Как я могу отправить технические документы?

    лучшая защита от такой ситуации – прописать в договоре требования к предоставлению документов, а главное, указать последствия нарушения:

    • убыток за каждый день просрочки в предоставление документов после доставки товара;
    • условие отсрочки платежа по договору при отсутствии технической документации;

    При приемке-сдаче товара можно также указать обязательство отправить товар и техническую документацию и потом не оплачивать договор до подписания договора. действовать.

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

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

    В жалобу также возможно включить требование об оплате и санкции со стороны поставщика за ненадлежащее исполнение договора.

    Если договором не предусмотрено иное специфический условиях возможно заключение дополнительного соглашения с указанием срока предоставления документов и права отсрочки платежа. до передачи технической документации.

    В случае отказа поставщика от заключения дополнительного договора действовать следующим образом:

    • Оплатить полученный товар. В противном случае поставщик имеет право потребовать неустойку.
    • Отправьте письмо с жалобой, как описано выше. С указанием возможности решения до обсуждения вопроса.
    • Юридические действия.

    Суд может уменьшить размер штрафа в соответствии со статьей 333 Гражданского кодекса Российской Федерации в случае явного завышения его размера в иске.

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

    Источник

    Поделиться с друзьями
    Решатор