Привет, Хабр! Меня зовут Роман Блинов, я ведущий технический писатель в «Цифре» — в команде по развитию платформы ZIIoT. Этот пост будет о подходе Docs-as-code для документирования разработки ПО. Пишу с прицелом на тех читателей (то есть писателей), кто этот подход пока не пробовал и по факту имеет набор файлов в Confluence, файлы формата .docx и .pdf, на поддержку, обновление и оформление которых тратится порядка 70 % времени (а хотелось бы меньше), и 101 отговорку разработчиков, чтобы не участвовать в документировании.

Сначала расскажу, с какими проблемами сталкиваются писатели до перехода на Docs-as-code, затем опишу подход в общих чертах и в конце упомяну об основной трудности его внедрения по собственному опыту и опыту коллег.

Привет, Хабр!

Компания АльфаСтрахование, как и многие другие, столкнулась с необходимостью замены используемых инструментов в связи с санкциями. За последний год мы отказались от Slack в пользу open-source аналога Mattermost, а Jira не без сложностей была заменена на Kaiten.

В нашей команде, которая занимается системой электронного документооборота в части операционных процессов, часто на голосовых встречах и при обсуждении в мессенджере Mattermost возникала необходимость накидать черновики задач в таск-трекер, чтобы потом их дозаполнить. Эта потребность наложилась на мое желание попробовать написать что-то на python, связанное с Chat-Ops.

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

Что такое Docs as Code классно описано в статье Docs as Code: введение в предмет.
В двух словах: это ведение документации на языке разметки (Markdown, AsciiDoc) с хранением в репозитории.
Плюшки — все вытекающие от работы с репозиторием.
Минусы — в этой статье.

На осенних Analyst Days прошлого года добрая четверть докладов была посвящена теме Docs as Code. На тот момент конклав аналитиков на моём прежнем месте работы уже 9 месяцев решал, нужен ли на проекте модный-стильный-молодёжный Docs as Code или всё же остаться в дышащем на ладан Confluence. К чему пришли — не знаю. На новом месте работы мы внедрили Docs as Code за неделю — было чёткое понимание проблематики, подход казался выигрышным решением. Используем полгода.

Я начинал карьеру как фронтенд-разработчик и прошел по всем стандартным этапам: от джуниора до сеньора и тимлида, потом стал руководителем отдела. И дальше, конечно, планировал стать CTO — Chief Technical Officer. И только через несколько лет узнал, что мои представления о том, какие навыки нужны на этой должности, были далеки от реальности.

В статье я расскажу о том, как я стал CTO в крупной компании и на своем опыте узнал о законах этого жанра. Если вам интересно, в чем заключается такая работа, или — вдруг — вы тоже готовитесь занять эту роль, добро пожаловать под кат!

Предположим, вы в системных аналитиках недавно, например, на позиции джуна. Вы уже представляете, в чем заключается работа, и планируете развиваться в этой сфере. Еще с вами багаж общих IT-знаний, умение гуглить и/или грамотный ментор.Через какое-то время вы осваиваетесь в изначальном проекте. Но системная аналитика, как оказалось, штука очень интересная. Поэтому вы начинаете искать, во что бы еще вляпаться — в своей статье говорю про развитие soft skills. Случаи, когда базовых hard skills нет совсем, здесь не рассматриваются.

Короче, как жить и набраться опыта аналитику, когда почти научился жить и еще не сошел с ума!

Как написать хороший SLA (Service Level Agreement, оно же Соглашение об уровне сервиса). И какой SLA будет хорошим.

Эта статья является попыткой обобщить имеющийся опыт, а также на неё я собираюсь ссылаться, когда меня будут в дальнейшем спрашивать, как должен выглядеть SLA. Работая в индустрии не первый десяток лет, я к своему удивлению регулярно сталкиваюсь с серьёзным непониманием основ, на которых строится SLA. Наверное, потому что документ довольно экзотический. После прочтения данного текста, я надеюсь, у вдумчивого читателя точечки над ё должны встать на свои места. Целевая аудитория — те, кто пишет SLA, и им сочувствующие.

Эта памятка писалась для внутренних нужд (открыть глаза менее опытным в вебе коллегам). Но, т.к. я насмотрелся велосипедов от довольно уважаемых, казалось бы, контор, — выкладываю на хабр. Мне кажется, многим будет полезно.

Зачем

Надеюсь, читающий уже понимает, зачем ему вообще нужен именно REST api, а не какой-нибудь монстр типа SOAP. Вопрос в том, зачем соблюдать какие-то стандарты и практики, если браузеры вроде бы позволяют делать что хочешь.

• Стандарт HTTP это стандарт. Его несоблюдение вредно для кармы и ведёт к постоянным проблемам с безопасностью, кэшированием и прочими "закидонами" браузеров, которые совсем не закидоны, а просто следование стандарту.
• Велосипеды со всякими {error: "message","result":...} невозможно нормально тестировать и отлаживать
• Поддержка большим количеством готовых клиентских библиотек на все случаи жизни. Те, кто будет вашим api пользоваться, скажут большое человеческое спасибо.
• Поддержка автоматизированного интеграционного тестирования. Когда сервер на любые запросы отдаёт 200 ОК — ну, это такое себе развлечение.

О чем это