Бях много развълнувам да започна да чета това издание. От доста препоръки от професионалните среди разбрах, че си струва да бъде прочетено. Написана е от екип от разработчици на техническа документация, което дава много полезен практически опит, свързан с реални казуси.
Изданието, което държа в ръцете си е второто и преработено, което е подобрено на базата на отзиви и коментари от професионалната потребителска общност „Write the Docs”, в която наскоро започнах да членувам. Именно оттам получих и едната препоръка. Литературният клуб създаде много подробни бележки, които са взети предвид от авторите и издателството. Това придава на книгата още по-голям авторитет. Надявам се, че прочетената информация ще ми бъде полезна. Въведението към второто издание включва и подробен списък на главите и нововъведенията в тях от преработката. Разбира се, това включва и подробни стилистични подобрения, както и други редакции.
Предпоставки
Много важно за мен като професионалист в дадена сфера е винаги да намирам адекватни за времето обучителни материали. Изглежда, че именно хора като мен са целевата аудитория, защото има множество важни допълнения и включва информация, която е особено необходима, а е трудна за откриване и систематизиране. Във въведението се говори за целта за написването на изданието, а то е да представи как реално се работи „по стандарт“ – спазване на методологии на работа, стилистични правила, както и взаимодействие с други участници в процеса на разработка.
Практически това означава, че конкретно за някои глави от книгата е било нужно авторите да направят свои собствени проучвания, така че да задоволят цялостните изисквания на такава целева аудитория. Въведението конкретно посочва и някои от особеностите и разликите с други издания от тази категория:
- Книгата включва множество препоръки и примери за работа с екипите по качествен контрол (QA), които са неизменна част от всяка една компания, касаеща разработка на продукт
- Дискутира се подробно работата с колеги от отделите по продуктово управление и поддръжка на клиенти
- Създаването на техническа документация и информационни материали по реда на Agile методология
- Съвместна работа с дистанционни екипи
Разбира се, книгата не е изчерпателен учебник, а по-скоро наръчник за професионалиста, който е създаден на базата на реално работещи примери и създаден най-вече от необходимост.
Целта на това ревю е по-скоро да отбележа неща, които са ми направили впечатление и биха били общополезни за всякакви специалисти, които работят с информация. Не си поставям за цел да реферирам или да обобщавам книгата. Смятам, че всеки заинтересован от този тема би следвало сам да прочете книгата и да придобие представа за темите и опита, който се съдържа в нея. Няма и да се спирам върху всяка една глава, а само там, където смятам, че има необходимост от повече внимание. Със сигурност ще трябва сами да прочетете книгата, за да добиете пълната представа за дълбочината на материята.
Agile
Работата по методология изисква от нас да следване някои специфични добри практики, така че да впишем в ролята си като създатели на съдържание. Професионалното ни задължение да създаване документация и други материали се определя и от някои супер важни характеристики, които трябва да притежаваме: адаптивност и проактивност. Причината за това е, че по принцип основния фокус винаги се залага върху самата разработка на продукта. Чест страничен ефект е не толкова добрата комуникация с екипа по разработка на документация. Затова и трябва да си поставяме за цел да се стремим да бъдем „интегрирани“ в цялостния процес.
Някои от добрите съвети и стъпки за по-добрата комуникация с другите колеги са създадени в този кратък списък:
- Да имаме достъп до всяка една дискусионна (чат) група, за да може да следим различните разговори по теми
- Да бъдем включени в електронните списъци
- Да преглеждаме таблата на Agile екипите
- Да участваме във възможно най-много дневни срещи, отчети, спринтове и планирания. Това включва също демонстрациите и сесиите по ретроспекция
Важна цел е да се създаде чувството в цялостната организация, че разработката на дадена функционалност или продукт не е завършена, докато няма готова документация. Авторите отбелязват, че една от добрите практики и правила на информационните е употребата на постоянен цикъл за обратна връзка. Това включва употребата на най-различни по вид комуникационни средства: форуми, чат стаи, директна и индиректна личностна комуникация, потребителски групи, конференции и др.
Хубаво припомняне е факта, че Agile методологията се списва най-добре при приложения, които са разработени за облака или Интернет средата. Причината е, че промени в програмния продукт могат да бъдат правени в работещата среда и това не обвързва клиентите към сваляне на обновления на тяхното локално устройство. Според авторите най-трудно се оказва разработването по тази методология при бизнес софтуера, който разчита на специално конфигуриране за определени индустрии и цели. Подробни примери за прилагането на Agile в различни по вид начини на доставка са представени в тази глава.
Книгата задава и списък от документация, която не е определена за конкретен екип и е универсална за компанията. Като създатели на съдържание тя се вписва в общите задължения: бележки по изданието, информация при възникнали проблеми, миграции към по-нова версия на програмния продукт, цялостно обновяване, добри практики, обучителни материали, документация към библиотеки и др.
В тази връзка се разглеждат и някои от задълженията, които имаме извън изработката на някакъв вид информация: разработката на персони за потребителското изживяване, обучение на колеги и клиенти, редактиране, подобряване на съществуващото съдържание, както и работа с получената обратна връзка.
В Agile ключово се оказва и включването не само като директен участник в сесиите на различните екипи, но също и създаването на отделен Scrum, който да е отделен за авторите на техническа документация.
Авторите посочват, че работата в такава обстановка включва комплексни процеси, които могат да бъдат обяснени чрез кръгова диаграма:
Кръгов модел на Agile разработка
Целева Аудитория
За разлика от някои други позиции в повечето технологични компании, авторите на техническа документация работят всъщност с два вида аудитория. Може би това не е толкова добре познато, затова и това се дискутира в подробности:
- Аудитория – Това са потребители и клиенти, които могат да се различават в своя опит, знания, бизнес роля или специфична употреба спрямо документацията и съответно продукта.
- Персона – Това е изграден архетипен персонаж, който дефинира конкретен тип представител.
За мен лично факторите при създаване на техническа документация спрямо тези два типа целева аудитория е от съществено значение. Много често трябва да взимаме решения спрямо това как най-добре би се разбрала информацията от тези два основни типа ползватели.
Доброто познаване на аудиторията позволява да се подобри не само създаването на информация, но също и да доведе до добри практики при нейното разпространение и публикуване.
Хареса ми много подробния опит, който е описан при структурирането на съдържание. Книгата дава много добри разяснения как на базата на опита с аудиторията бихме могли да оптимизираме нашата документация.
Добрите практики мога да обобщя в два основни типа: тези, които засягат самата структура на документа (разбиването на параграфи, дължина и т.н.) и смислови решения. По втората точка има написано много, но само някои от идеите, които влизат тук включват фактори като запознатост с терминологията, дефинирането на термини, както и създаване на локализирани версии за дадени езици и региони.
Не е за пренебрегване и факта, че може да ползваме като източници на информация и опита на колеги, както и вътрешна документация, за да създадем най-оптимизирания и добър вариант, подходящ за клиентите.
В тази глава има и подробни съвети за колаборативното съавторство за целите на създаване на различни видове съдържание. Споменава се и как трябва да бъде създадена програма за проверка на качеството на документ през независимия прочит.
За мен лично беше много полезна и частта, свързана с работата с потребителската общност. Дадоха се много практически примери и съвети, които със сигурност смятам, че биха полезни за всеки един специалист. Именно от тази глава смятам, че мога да попрочета малко повече за управлението на общността. Има и такава професия „общностен мениджър“, която вече се реализира успешно в много компании. Страхотен пример е Jono Bacon, който дълго време заемаше такава позиция в Canonical.
Документация на продукти от трети страни
Тази глава е особено ценна за мен, тъй като дава много полезни насоки за една област, която не винаги е добре дискутирана сред специалистите. Сложните казуси по документиране на функционалности и продукти на трети страни, които по някакъв начин са свързани с нашите собствени проекти, са особен случай. Книгата разяснява в много подробности по планирането и осъществяването на този процес, но също и при какви условия и до каква дълбочина това би било най-ефективно.
Авторският колектив се е постарал и да създаде една изключително полезна диаграма, която веднага ще си сложа на бюрото. Систематизирането на такъв тип решения в алгоритъм наистина не е лека задача, а предлагането на този безкрайно полезен инструмент е незаменимо.
Учебни цели
Методите на работа чрез създаване на учебни цели и фокусирането върху необходимостта от информация е супер важно. Много ми харесва, че има създаден класификатор на видовете цели според типологията им. Струва ми се уместно да ги спомена тук:
- Осведоменост – Включва способността на потребителите да могат да опишат или перифразират дадена концепция, функция или списък от възможности.
- Разбиране – Това описва способността на потребителите да могат да правят информирани решения за това как дадена концепция или функция може да се приложен към техния собствен случай.
- Приложими умения – Това е придобиването на възможността на потребителите да следват инструкции, за да могат да изпълнят дадена задача.
Улесненията в създаването на информация, която се основават на тази платформа са описани подробно в следните направления: по-лесно проучване и писане, по-лесна организация, по-лесна поддръжка и по-лесна употреба. Именно в тази глава има и специално създадена матрица, която позволява по-лесното формулиране на критериите и планирането.
Разработка на информация според сценарий
Разработването на сценарий е от особено значение, когато става дума за документиране на определени теми. Това е метод на работа, който се подчинява на една специфична цел: създаването на списък от теми, които да предоставят цялостно разрешаване на конкретен проблем или изпълнението на някаква цел. Важното в този случай е необходимостта от представянето на проблем от реална ситуация, за да може максимално добре да се илюстрира тази необходимост.
В тази връзка трябва да се разграничи сценария от типичните инструкции, които имат основна цел да обяснят дадена концепция. Сценарият е точното впрягане на идеята и информацията за употребата на дадената концепция в точен и конкретен вид. Това е много полезно при представяне на функции от особено значение, защото дава работеща перспектива и как това се вписва в определения бизнес модел.
Инструменти и представяне на съдържание
В тази глава се дискутират някои от моите любими теми, а именно как ефективно могат да се представят различните изготвени информационни материали. Винаги съм се стремял да бъда добре информиран за различни подходи, както и добрите системи за управление на съдържание. Интересното е, че тук намерих много по-конкретна информация, специално направена за професионална употреба. Сведени са до абсолютния минимум типичните заучени фрази и се дават много задълбочени познания по темата.
В тази част от книгата се дискутират различните подходи към създаване на документация – от една страна това е работата в някаква определена среда, но това може да бъде и чрез използване на инструменти като Git. Не липсва и споменаването на XML-базираните формати като DITA, на маркъп езиците като Markdown и други начини. Всички те са посочени по начин, който да дава възможност на нас да изберем най-доброто съобразно нашите изисквания и нужди. Систематизирането на информацията по тази тема е практически безценно!
По време на цялата тази дискусия се говори и за конкретни метрики и SEO индикации, които също биха могли да бъдат използвани в цялостната стратегия и планиране. Книгата дава и съвети при някои определения решения, така че предварително да сме наясно с някои от опциите и възможностите при тях.
Някои от темите, които се дискутират тук са следните (правя този кратък списък като подсещане):
- Създаване на PDF изходни файлове
- Повторна употреба на готовото съдържание
- Управление на хипервръзки
- Употребата на маркъп езици срещу визуалното редактиране
- Интегриране на уики съдържание с други системи
- Дефиниране на роли за достъп
Тази глава дава и подробен преглед на това как уики-базираната структура може да бъде използвана за целите на създаване на цялостна документация.
Разработка на SaaS документация
За мен лично това е една от най-интересните глави от книгата. В днешният бум на всякакви софтуерни решения, които се развиват с изключително бързи темпове, документацията има огромна роля. От много години (още преди да се занимавам професионално с тази област) винаги съм харесвал т.нар. „rolling release” модел на разработка, който на практика се явява като отличителна характеристика на облачните услуги.
Точно заради тези характеристики има и глава, която специфично се занимава с тези въпроси. За справянето с тази трудна задача трябва да се имат предвид и някои от ограниченията на този тип платформи, най-вече свързани с конкретните нужди на техните клиенти. Някои от обособените компоненти, които са свързани с тoва включва и следните типове информация: вътрешна документация, материали за подготовка на нова версия, крос-функционални информационни материали и т.н.
Тази глава дава задава и три ключови компетенции, които са свързани с успешното създаване на информация:
- Посрещането на очакванията на аудиторията
- Гъвкавата роля на разработчика на информационни материали
- Нуждата от създаване на подробна вътрешна документация
Изключително интересна част от книгата е това и си заслужава да бъде четена и препрочитана многократно, за да може да се усвоят всички важни особености. А те наистина имат значение.
В заключение
Съзнавам, че това е практическо много кратко и частично ревю, но се постарах да включа само това, което ми се струва важно и ново. Всеки човек има различен опит и затова смятам, че книгата би била подходяща за всеки един професионалист от сферата. Вие ще разберете нови неща за себе си.
За мен достойнството на това издание е, че препълва от реални и практически примери от ситуации, които аз самия съм преживял. Със сигурност поне половината диаграми и таблици ще принтирам и ще залепя на бюрото в офиса. Благодарен съм на авторския колектив за наистина положения труд. И макар книгата да не претендира да бъде учебник, за мен тя има изключително висока образователна стойност.