Як “для себе писав” впливає на якість роботи інших

або “Наскільки важливо якісне написання документації в роботі програміста?”
або “Чи важливо мати навички якісного написання тексту будучи програмістом?”
або “Чи не заважає програмістові бути також і блогером?”

Отож, йшов я по дорозі з роботи додому і вже тоді задумав новий пост. І ось я пишу, про важливість навичок письменника чи блогера в роботі програміста. На перший погляд не поєднувані речі, але в моєму випадку, це ключ до успіху, ключ до якісного розуміння задачі.

code

Переді мною було завдання, яке вимагало зрозуміти нові речі, відтворити кроки, які хтось подібно вже робив в минулому. Свого роду – “Читаєш інструкцію на ~100500 кроків” і “Робиш так само”. Все ніби просто, але:

  • інструкція була написана майже пів року тому, ніхто її не оновляв, отже дещо в кроках було не точно.
  • інструкція була написана простим стилем: текст + посилання.
  • все в формі довжелезного списку з під пунктами.
  • текст простий, без виділення, одноманітний, не читабельний.
  • посилання повні, не прикриті, довжелезні, не читабельно.

Поз-за не-читабельності, один із кроків прослизнув повз мою увагу, бо я не зауважив, що то крок взагалі 🙂

І тут варто згадати трохи моєї історії.
Ще в роки 2004-2006 я став активним користувачем форумів, полюбив написання тем, їхнє форматування, вираження важливих речей, і так далі. Вже в 2010-му я стартував свій перший блог – прототип цього блогу про роботу. Потім появились інші блоги (2011-2011). Тут ось більше про це. Одним словом я любив і люблю писати 🙂 будь що, будь де.

Програміст, який ту документацію написав, сказав – “Ну, я для себе писав“. І тут мене, як блискавкою …

  • Як так? Невже люди для себе так просто пишуть текст, і їм цього достатньо?
  • Чому я будучи також програмістом, всі документації пишу в форматі “Rich text”?
  • Чому всі user story в мене виглядають як книжки, як витвори мистецтва?
  • Ряд людей не дасть мені збрехати, як мої емейли типу “Short Summary” легко переходять на рівень опусів.
  • Чому wiki pages в мене мають і заголовки і жирний і курсивний текст і гарно оформлені посилання?
  • Чому я вважаю, що в таких випадках інформація є більш читабельною?
  • Чому я вважаю, що до роботи навіть програмістом, навички якісного написання тексту це необхідна річ?

Я не хочу бути бізнес аналітиком, чи власником бізнес продукту, якщо ви скажете що мені туди дорога. Я хочу чітко розуміти технічні завдання для втілення в коді. І для цього я хочу мати якісний документ, і головне читабельний.

І ось після таких питань в секунду часу, я вирішив обновити ту документацію.

  1. Я додав звичайно більше фото – вирізок екрану, щоб було більш зрозуміло про що йдеться. Бо візуальний контакт з текстом і реальність є дуже важливим нюансом.
  2. Через декомпозицію, я виділив в тексті основні групи, і об’єднав їх в H1 заголовки.
  3. В тексті тепер присутні як і жирний так і курсивний стиль.
  4. Текст, в якому важливу частину займають куски коду, виділив відповідним стилем, щоб було читабельно, що це КОД :)
  5. Решту тексту, розташував також в формі списків, але тепер це було читабельно, бо замість 100500 кроків6 я тепер читаю декілька головних груп, які дають можливість легкого і швидкого читання.
  6. Посилання звичайно правильно оформив і загальний текст тепер набагато компактніший, а функціональність не зменшилась.
  7. Звичайно я подав інформацію про дату першої версії та дату мого оновлення. Таким чином, в майбутньому люди будуть читати і розуміти історію документу. І маючи посилання на людей-авторів, легко можна знайти ще більше деталей.

І сказав я “Це добре, тепер це читабельно”.

аля Висновок

Бути програмістом, це не тільки кодити мегатони так званого гав*о-коду, і тішитись потім що воно працює на костилях (в цьому тексті ви маєте бачити мегетони мого сарказму); це не тільки написання крутого коду для себе; це не тільки код. Це також “програма” для майбутніх людей, які будуть читати цей код, виправляти помилки, перевіряти документацію. Бути програмістом, це заглядати в майбутнє, користуючись своїми навиками аналізу та подання якісної інформації у вигляді тексту. Навіть на рівні байт-коду, знаючи який текст вписати – можна вирішити важливі проблеми. Так текст – це основна зброя програміста.

Можливо не всі програмісти з такою думкою погоджуються. Можуть казати багато речей.
Але блогери, письменники, журналісти, які поважають себе та свою якісну працю, більше ніж впевнений розділяють мою точку зору. Щоб там не казали, а я знаю що краще для мене.

PS. Я навіть клієнту розказую, що треба писати якісно, що технічні завдання мають бути оформлені в гарному форматі. Якщо клієнту пофіг, я беру сам і виправляю, і потім ті ж завдання виконую. Це я до того, що не важливо як документація написана, я її для себе завжди можу зробити кращою 🙂

Advertisements

One thought on “Як “для себе писав” впливає на якість роботи інших

  1. робота з текстом то ціла наука. напр коли не в западло ставити розділові знаки тощо
    читати недбало написаний текст – то є мУка для мозку.

    На цьому, думаю, тег </sarcasm> можна закривати, — навіть від двох рядків очі кровоточать. Андрій, ти підняв дуже важливу тему. Пофігізм до тексту — то поширена біда.

    Але з цією бідою можна боротися. Напр., вивчивши мінімум з markdown (b, i, link, code, списки).
    Після цього прийде дзен довгого тире, нерозривних пробілів, м’якого переносу та гармонії кегля абзацу.

    Вправа на домашнє завдання: написав доку — попий кави і подивися на неї через 10 хв. Вкурвить — покращ. Кайдзен.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s