Рубрика «документация»

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

image

Ну а что там еще можно улучшить или придумать — спросите вы. Давайте поразмышляем на эту тему — можно ли как-то улучшить наш опыт взаимодействия с таким важным но так часто игнорируемым аспектом программирования как документация в коде, или по-простому комментарии.
Читать полностью »

Многие уже давно или активно используют или смотрят в сторону модели хранения и публикации документации как кода, это значит применять к документации все те же правила, инструменты и процедуры, что и к программному коду, например, хранить в репозитории, прогонять тесты, собирать и релизить в CI/CD. Этот подход позволяет поддерживать документацию актуальной к коду, версионировать и отслеживать изменения, используя привычные инструменты разработки.

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

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

Итак...

Статические переменные, в php это особый вид переменных, которые объявляются при помощи ключевого слова static.

static $foo = 3;

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

  1. могут быть присвоены только константы и константные выражения
  2. время жизни статической переменной не ограничено временем жизни области видимости в которой она была объявлена
  3. могут быть определены в скрипте лишь однажды
  4. не уничтожаются до конца выполнения скрипта

Теперь по порядку.

1. Могут быть присвоены только константы и константные выражения

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

Читать полностью »

image

Несколько месяцев назад я закончил один из этапов своего профессионального пути многорукого Шивы в стартапе по разработке системы управления лабораториями неразрушающего контроля. Я расскажу как мне удалось задокументировать часть разработки связанную с подключением и генерацией документов в достаточном объеме для дальнейшего спокойного использования созданной системы в течении двух лет.
Читать полностью »

MS Word регулярно подкидывает нам «сюрпризы»: «съехавшие» скриншоты, «плывущие» таблицы, пустые страницы при печати. Эта статья о том, как мы искали замену MS Word, (спойлер — не нашли), а нашли возможность глобально улучшить наш процесс работы с документацией.

imageЧитать полностью »

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

Для общего понимания разберем 3-варианта передачи информации заказчиком, компании исполнителя, для реализации VR проекта.
Читать полностью »

Привет!

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

26 июля, Deworkacy — DocOps от Ростелекома - 1

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

В общем, в пятницу, 26 июля, мы в 19.00 собираемся в Deworkacy (Москва, Берсеневская набережная, 6, стр 3) и начинаем документировать говорить про документацию. Список докладов — под катом.
Читать полностью »

Семь «абсолютных истин» джуниора, от которых пришлось отучиваться - 1

Скоро наступит десятый год, как я профессионально занимаюсь программированием. Десять лет! И кроме формальной работы, почти две трети своей жизни я что-то создавала в интернете. С трудом вспоминаю годы, когда я не знала HTML: даже странно, если подумать об этом. Некоторые дети учатся музыке или балету, а я вместо этого создавала волшебные миры, кодируя в своей детской.

Размышляя об этом первом десятилетии регулярного получения денег за ввод странных символов в терминал, хотелось бы поделиться некоторыми наблюдениями, как изменилось моё мышление за годы работы.
Читать полностью »

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

Как оживить документацию? - 1

На web-проектах Альфа-Банка используется фреймворк для автоматизации тестирования Akita, который использует для BDD-сценарии. К настоящему моменту фреймворк набрал большую популярность благодаря низкому порогу входа, удобству использования и возможности тестировать верстку. Но мы решили пойти дальше — на основе описанных тестовых сценариев формировать документацию, тем самым сильно сокращая время которое аналитики тратят на на извечную проблему актуализации документации.

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

  • скриншоты;
  • значения переменных (config File, учетные записи пользователей и т.д.);
  • статусы и параметры запросов.

Мы посмотрели на наш существующий плагин, который был, по сути, статическим анализатором и формировал документацию на основе описанных в .feature-файлах сценариев. Решили добавить динамики, и для того, чтобы не городить плагин над плагином, приняли решение написать свой собственный.
Читать полностью »

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

Рассказывает Юрий Никулин, руководитель службы разработки технической документации.

Для начала давайте определим, что такое производительность. В классическом понимании, это время на производство единицы продукции или количество продукции, произведенное в единицу времени.

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

Читать полностью »


https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js