Pull to refresh
62
Karma
0
Rating
Алексей Кутумов @prograholic

Руководитель команды разработки

Вам кажется, что с вашей документацией что-то не так? Вам не кажется

Reading time 14 min
Views 10K
Конференции Олега Бунина (Онтико) corporate blog Project management *Technical Writing *


Меня зовут Семён Факторович, с 2012 года я занимаюсь технической документацией. Последние три года я руковожу собственным агентством documentat.io, помогая российским IT-компаниям создавать качественную документацию.


Мы пишем документацию с нуля (руководства пользователя, справочники API, архитектурную документацию) и поддерживаем уже имеющуюся и проводим консультации по настройке документационных процессов. И почти каждый запрос от наших клиентов начинается с признания: «Кажется, с нашей документацией что-то не так».


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


1) Документация полностью отсутствует.
2) Документацию неохотно пишут.
3) Документацию неохотно читают.
4) Документация есть, ее пишут и читают, но она кажется бесполезной.


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


Эти проблемы я и хочу сегодня обсудить: посмотрим их симптомы и как их интерпретировать, а самое главное — что с ними делать. Предлагаю вам некую методичку по самодиагностике и самолечению проблем с вашей документацией. Всё, приведенное ниже, опробовано на нескольких десятках IT-компаний.


Читать дальше
Total votes 25: ↑25 and ↓0 +25
Comments 4

Как вернуть контроль и уменьшить зависимость от смартфонов и уведомлений

Reading time 5 min
Views 20K
Edison corporate blog Interfaces *Usability *GTD *Health
Translation
image


Данные от 200 000 пользователей iPhone

Тристан Харрис — борец с Facebook, Google и другими крупными корпорациями. Его называют «Совестью Кремниевой долины». Его основной посыл — что тысячи специалистов в сотнях ИТишных компаниях борются за то, чтобы вы отвлекались от полноценной жизни и залипали в телефон. У него интереснейшее выступление на TED и несколько переводов на Хабре.


В этом переводе даны практический советы, как понизить власть приложений над вашей жизнью.
Читать дальше →
Total votes 31: ↑22 and ↓9 +13
Comments 50

Аллюр три креста, или Почему проекты так трудно закончить в срок

Reading time 12 min
Views 14K
Project management *
Sandbox
Один крест (+) означал, что посыльный мог ехать к месту назначения шагом, два креста (++) означало рысь, три креста (+++) — незамедлительный галоп. Поэтому в армии галоп носил неофициальное название аллюр три креста, а позже это выражение вошло в русский язык, имея смыслом максимально быстрое выполнение поручения начальства. [Википедия]
Tar pit (англ., дословно смоляная яма) — 1) неразрешимая проблема, 2) битумное озеро (место, где подземный битум выходит на поверхность, создавая участок природного асфальта). [Англо-русский словарь] Животные, попавшие в битум, не могут выбраться обратно, поэтому такие озера являются отличным местом для раскопок доисторических скелетов [Википедия].

«Воображение представляет динозавров, мамонтов и саблезубых тигров, пытающихся высвободиться из смолы. Как бы ни был силен или ловок зверь, в конечном итоге ему уготована гибель. Такой смоляной ямой в последнее десятилетие было программирование больших систем...» [1, с.16] С этого яркого образа начинается классическая книга Фредерика Брукса, впервые увидевшая свет в далеком 1975 году. Другая классическая книга, опубликованная в столь же древнем 1987-м, начинается ничуть не лучше: «А в это время где-то гибнет проект» [2, с.23]. Идут годы, человечество вступает в новое тысячелетие, но и в 2014 году очередной бестселлер начинается все с той же вечной истории: «3 марта 2010 года Федеральное бюро расследований решило приостановить свой крупномасштабный и многообещающий план модернизации управления информацией… В бюро пытались обновить свою компьютерную систему уже более десяти лет, и, похоже, их постигла катастрофа» [3, с.14].

Читать дальше →
Total votes 38: ↑37 and ↓1 +36
Comments 30

Yet another cool story about bash prompt

Reading time 10 min
Views 36K
VK corporate blog
Я программист. По крайней мере так написано в трудовой книжке. Почти всё своё рабочее время я провожу в консоли и текстовом редакторе. Мне очень нравится bash. Почти год я жил в zsh, прислушавшись к советам своих многочисленных коллег и знакомых, но в итоге я вернулся в bash и ни капельки об этом не жалею.



Zsh красив, приятен, чертовски функционален, но, признаюсь честно, я не смог совладать со всеми его многочисленными настройками. Я хочу работать, а не бороться со своим рабочим окружением. Простой пример: пару раз из-за автодополнения zsh я удалял все директории и файлы в текущей директории — zsh просто ставил пробел между автодополненной директорией и введённой мною звёзочкой (я хотел удалить всё в выбранной папке). Помните тот эпичный баг с пробелом и удалении директории /usr? У меня было то же самое. Спасибо гиту, выручил в который раз.

Впрочем, дело не в zsh — будь я чуточку умнее, я бы с ним обязательно справился бы, и всё было бы хорошо, но мы, суровые программисты, будем использовать bash и vim, а гламурные zsh и textmate оставим хипстерам и прочим модникам ;)

Я не напишу ничего оригинального и универсального решения я не приведу, но мне всегда нравилось читать конфиги и описания других людей, а если к ним были приложены интересные картинки, так я вообще перечитывал эти статьи несколько раз. Надеюсь, вам тоже будет интересно.
Читать дальше →
Total votes 175: ↑166 and ↓9 +157
Comments 143

Диспетчер произвольных сообщений на базе google protocol buffers

Reading time 6 min
Views 19K
C++ *
Sandbox
Появился свободный день, и я решил поиграться с библиотекой google::protobuf. Данная библиотека предоставляет возможность кодирования и декодирования структурированных данных. На базе этой библиотеки я построю простенький диспетчер, который может обрабатывать любые сообщения. Необычность данного диспетчера состоит в том, что он не будет знать типы передаваемых сообщений, и будет обрабатывать сообщения только с помощью зарегистрированных обработчиков.
Читать дальше →
Total votes 17: ↑17 and ↓0 +17
Comments 1

Information

Rating
Does not participate
Location
Новосибирск, Новосибирская обл., Россия
Date of birth
Registered
Activity