Як я можу задокументувати минулу роботу чужого? [зачинено]

У нас погана ситуація, коли ми маємо дуже мало документації щодо налаштування наших попередніх працівників, виготовлених під критичну для бізнесу систему. Багато змін було внесено в Crystal Reports, сутність баз даних та власні файли конфігурації / програмування для нашого програмного забезпечення ERP.

Поточна документація, як правило, говорить приблизно так:

Ця програма запускається перед виставленням рахунків. Відомі помилки: немає.

Запустіть цю програму після встановлення програмного забезпечення X.

Змінено такі поля у цьому звіті: (без пояснення того, як чи чому)

Наш ІТ-магазин невеликий, і що стосується програмного забезпечення ERP, більшість робіт було зібрано на одну людину (це я зараз), тому ніхто більше не знає, що ми все робили. Департамент інформаційних технологій та бухгалтерії знає шматочки та фрагменти (іноді дуже корисні), але цього недостатньо.

Іншою проблемою є те, що наш відділ бухгалтерського обліку, здається, вважає нас добре задокументованими. Це правда, що ми вели велику кількість записів про те, що пішло не так , але дуже мало пояснюють, що (якщо що-небудь) було зроблено для вирішення цих проблем. У нас є сотні паперів, що пояснюють помилки, але документи, що пояснюють зміни (як показано вище), майже марні.

Як я можу зайнятися документуванням минулих змін, коли я не знаю, що все було зроблено? Я можу почати з документування того, що ми змінили: Файли, таблиці баз даних і т.д., які нам потрібно мати для роботи системи. Я також можу документувати те, що ми робимо ; коли запускаються звіти, чому людям сказали використовувати X звіт / програму. Але коли у однієї з цих індивідуальних речей є проблеми, я завжди повертаюся до квадратного.

Як я можу активно задокументувати цей матеріал для себе та інших?

Я думаю, що це марні вправи. Якщо він працює, він працює, якщо він не працює, ви повинні це виправити.

Найкращий спосіб документувати старі речі - це коли ви працюєте над ним, документуйте те, що ви робите, і пояснюйте ділову логіку (яка, напевно, не була задокументована). Це буде великою допомогою для будь-якого нового розробника.

Говорячи про документування старого коду / речей, хтось повинен був ним володіти. Припустимо, це ваш поточний менеджер. Він / вона може не мати повних технічних знань про це, але буде знати, які зміни були внесені. У цьому випадку це не ваша робота. Може бути, менеджер може щось написати про це, які зміни були внесені. Це було б корисно зберегти як історію. Якщо виникає така проблема, ви можете зануритися в ці ділянки, які можуть бути дуже корисними для вас. Але входити в код і документувати зміни є досить марним IMO і, ймовірно, неможливо.

Відмовтеся від зусиль, щоб документувати зміни .

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

Чи є у вас контроль джерела?

Чи можете ви розібратися, що з цього змінилося?

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

Чи можливо воскресити стару поштову скриньку розробників? (не впевнений, чи це можливо з побоюванням конфіденційності чи ні). Можливо, буде багато інформації, яку можна отримати, потягнувшись туди.

Насамперед. Де ви зберігаєте свою документацію? Якщо ви ще цього не зробили, налаштуйте вікі. Я більше віддаю перевагу dokuwiki , і є навіть попередньо вбудований vm , якщо ви так схильні.

Це забезпечує деякі важливі особливості:

• Доступ до документів можна отримати в будь-якому місці мережі LAN (установка на новому комп’ютері ...)
• Усі документи знаходяться в одному місці
• Усі документи можна шукати
• Ви можете співпрацювати (новий колега, користувачі програмного забезпечення)

Тепер, якщо ваша документація у паперовій формі, то я бажаю вам найкращого. Якщо у вас є Word Docs, побудуйте сценарій імпорту .

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

Переходимо до більш конкретної документації, якщо вам потрібно працювати з джерелом для різних проектів, переконайтеся, що у вас створено належне середовище розробки ! Для переліку речей ви повинні мати:

• Контроль версій ( git , mercurial , fossil )
• Відстеження помилок ( trac , mantis , redmine , копалини )
• Система збирання ( Autotools , SCons , BuildBot )
• Контроль проекту ( затемнення , вказана структура каталогу, плагін редактора )
• Джерельна документація (README, TODO, INSTALL, коментарі до джерела)

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

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

Редагувати:

Відповідно до коментаря монтажу нижче, ще однією корисною справою є створення діаграм вихідного коду. У вільному коді є речі , і ця стаття перераховує деякі популярні мови.

Найкраще, що ви можете зробити, це задокументувати все, що ви знаєте, і попросити навколо компанії документувати все, що знають і інші. Я пропоную централізувати документацію у вікі чи щось подібне, щоб кожен мав доступ до найсучаснішої документації.

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

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

Удачі!

Коли я намагаюся документувати щось, що зробив хтось інший, хто більше не займається проектом чи компанією, я завжди починаю таке: "Це чорна скринька для всіх, включаючи мене, поки мені не потрібно щось змінити або пояснити комусь іншому".

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

Ви могли написати автоматизовані дослідницькі тести. Вони мають ряд переваг:

• Ви дізнаєтесь, як працює система під час їх написання

• Вони служать виконуваною документацією на потім

• Якщо ви запускаєте їх регулярно або навіть безперервно, вони забезпечують приємну мережу безпеки для виявлення, коли зміни щось порушують або коли їх потрібно оновлювати

Я не знаю, чи доцільно написати такі тести у вашому конкретному середовищі.