У сярэднестатыстычнай ІТ-кампаніі ёсць патрабаванні, гісторыя таск-трэкераў, зыходнікі (магчыма, нават з каментарамі ў кодзе), інструкцыі на тыпавыя, важныя і складаныя выпадкі на продзе, апісанне бізнес-працэсаў (ад онбордынгу да "як пайсці ў адпачынак") , кантакты, ключы доступу, спісы людзей і праектаў, апісанне зон адказнасці - і куча іншых ведаў, пра якія мы напэўна забыліся і якія могуць захоўвацца ў самых дзіўных месцах.
Веды =/= дакументацыя. Гэта нельга растлумачыць, гэта трэба запомніць
Як зрабіць так, каб тыя, каму спатрэбілася даведацца нешта з гэтага, разумелі, дзе і як гэта знайсці, а ўсё, каму трэба быць у курсе асобных рэчаў і дамоўленасцей, маментальна і дакладна маглі даведацца аб зменах у іх.
У фінальным выпуску падкасьце “Цімлід патэлефануе” хлопцы з Skyeng паразмаўлялі пра кіраваньне ведамі з Ігарам. Цупко - чалавекам з праграмнага камітэта KnowledgeConf і "дырэктарам па невядомаму" у Фланце.
Поўны запіс даступна ў выглядзе , а ніжэй мы сабралі некалькі цікавых парад і спасылкі на карысныя матэрыялы, якія згадваліся ў аўдыё або пашыраюць інфармацыю з яго. Будзе выдатна, калі вы таксама падзеліцеся хакамі і граблямі сваёй каманды ў каментарах.
Першы хак: вам больш не трэба ведаць, у якой з сістэм шукаць
“Я ўзяў нашыя крыніцы ведаў і зрабіў па іх агульны пошук: такое адзінае акно з сістэмай фільтрацыі, каб паменшыць вобласць пошуку. Так, пры гэтым усё яшчэ трэба сачыць за яго якасцю, папаўняць базы ведаў, змагацца з дуплікацыяй і памылковай інфармацыяй.
Адзін змацаеш, каб знайсці вось-гэта-ўсё
Але ўжо цяпер каля 60% інжынераў Фланта карыстаюцца гэтым пошукам мінімум 1-2 разы на дзень – і звычайна знаходзяць адказы на першай-другой пазіцыі. А ў выглядзе proof of concept ляжыць індэксаванне гугл-дакументаў: усе доксы, тэчкі, ван драйвы і гэтак далей – гэта ўсё таксама папросту ўганяецца ва ўнутраны пошук”.
Другі хак: як не ўпусціць крытычна-важнае ў кучы чатаў
“Калі вы працуеце ў размеркаванай камандзе, то напэўна прыкметная частка вашага дня праходзіць у Slack – і ў выпадку чаго вы прывыклі рабіць неяк так: “@myteam, дапамажыце/глядзіце/упісаць патрэбнае…”. Але ёсць праблема багацця інфармацыі - і асобнае згадванне можна прапусціць сярод іншых паведамленняў.
Нам у Skyeng дапамагае бот, праз якога можна напісаць паведамленне і цягнуць любую колькасць людзей або груп. Выкарыстоўваем у выпадках, калі рэальна важна, каб людзі прачыталі ці адрэагавалі: ён будзе бясконца тыкаць, пакуль не націснеш кнопачку “Я прачытаў” — прапусціць ці праігнараваць не атрымаецца”.
Пытанне на засыпанне: што рабіць з дакументацыяй?
“Вельмі шмат ведаў зыходзіць ад тэхнароў, але не ўсе ўмеюць іх добра апісваць.
Бо ў цябе няма ніякага кампілятара ці лінтара, які сказаў бы, правільна ты робіш ці не - і часта на выхадзе мы маем незразумелы, дрэнна аформлены і няпоўны тэкст. Вядома, рабіць нармальна трэба не таму, што нехта прыйшоў і сказаў "трэба" — ты сам сабе ж добра робіш: праз месяц-другі прачытаеш і зразумееш. Ды і іншы чалавек, адчыняючы доку, не будзе тут жа зачыняць яе назаўжды, разумеючы, што яна ніякая.
Частка падкасьце, прысвечаная пытанню "Колькі трэба чалавек, каб напісаць добрую дакументацыю або зрабіць нармальнае дэма"
Але застаецца пытанне: а колькі часу на гэта выдзяляць і як якасна рабіць?
І калі тут ёсць сумленны адказ: калі не будуць уцягнутыя людзі з бізнэсу, і калі яны па-эмпірычнаму не адчуюць аддачу ад добрай дакументацыі, ёсць рызыка, што спробы дадуць малую аддачу. Гэта больш гісторыя пра змену культуры.
А ў астатнім, вас выратуюць досвед і настаўніцтва. Тут могуць падысці аналагі парнага праграмавання, трэкінгу прагрэсу і код-рэўю — паказ лепшых практык, тыканне ў памылкі і нуджэнне ўрэшце”.
Бонус: “Ды добра, я ім так раскажу, зразумеюць”
Пытанне "а колькі часу на гэта марнаваць і на якім узроўні рабіць" важны не толькі ў рамках дакументацыі, а ўвогуле для перадачы любых ведаў. Дэма - таксама выдатны прыклад абмену інфармацыяй. Але ёсць нюансы: напрыклад, як зрабіць так, каб яны мінімальна забіралі час.
Канал абмену ведамі сярод распрацоўкі: унутраныя даклады, карысныя кнігі, артыкулы і г.д. Структураваная выцісканне таксама захоўваецца ў Notion.
Збольшага гэтыя праблемы дапамагае вырашыць практыка ўнутраных дакладаў. Раз на тыдзень бярэцца 40-60 хвілін у не самы нагружаны час - і хлопцы робяць даклад па відэа для калег з розных праектаў. Каманда фронтэнда ключавога прадукта - Vimbox - аб сваім UI kit, які можна тэматызаваць пад любы іншы праект. Каманда маркетынгавай распрацоўкі - пра бібліятэку для трасіроўкі і лагіравання запытаў, якая тут жа зацікавіла яшчэ некалькі праектаў. Каманда праекта "Матэматыка" падзялілася вопытам пераходу з REST API на GraphQL. Каманда групавых урокаў думае расказаць, як першай перайшла на PHP 7.4. І гэтак далей.
Спіс вядзецца з мая 2018-га і налічвае больш за 120 запісаў.
Усе сустрэчы-заводзяцца праз карпаратыўны Google Meet, запісваюцца і на працягу сутак аказваюць у тэчцы на агульным гугл-дыску, а спасылкі на запісы дублююцца ў той жа Slack. Гэта значыць, можна не прыходзіць, калі аўрал, а паглядзець потым на 1.5 хуткасці - звычайна сам даклад ідзе да 20 хвілін, а абмеркаванне - як атрымаецца. Але за рамкі гадзіны не выходзім)
PS А што спрацавала і не спрацавала ў вас?
Карысныя спасылкі:
- Радзіён Нагорнаў з "Лабараторыі Касперскага" пра тое, і чаму гэта не дакументацыя (дзякуй за спасылку каналу Ігара , там яшчэ шмат такога).
- Ігар Цупко з Фланта пра тое, у сябе ў кампаніі
- Аляксей Катаеў з Skyeng (прабелы ведаў па тэхналогіях і спецыфічных абласцях) у размеркаванай камандзе.
- Сяргей Ганчарук з Фланта пра данясенне інфармацыі , Калі сутыкнуўся з праблемай у размеркаванай камандзе.
Крыніца: habr.com