Методика й стиль викладення

Найважливіші методичні вимоги до теоретичної частини керівництва програміста – логічність і послідовність викладу. Зокрема, у тексті обов'язково повинні бути дотримані наступні правила:

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

- У читача ніколи не повинне виникати відчуття, що автор плодить сутності без потреби. Введення кожного поняття повинно бути чимось обґрунтовано.

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

При описі об'єктів особлива увага варто приділяти наступним аспектам:

- Що обов'язково повинно передувати створенню й використанню об'єкта.

- Які побічні ефекти звертання до об'єкта.

- Особливості інтерпретації об'єктом переданих йому даних.

- Де «фізично» (у якому файлі, у якій бібліотеці) перебуває об'єкт.

Бажано по кожному об'єкті привести приклади використання, невеликі фрагменти коду, що демонструють:

- створення об'єкта (якщо перед використанням його необхідно створити);

- передачу об'єкту вхідних даних;

- одержання вихідних даних і їхню інтерпретацію.

Опис об'єктів можна винести в окремий том або документ за назвою «Довідник програміста». Гарна думка – зробити його гіпертекстовим.

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

Типова структура

Структура керівництва програміста, зафіксована в ДСТ 19.504-79, така:

1. Призначення й умови застосування програми.

2. Характеристика програми.

3. Звертання до програми.

4. Вхідні й вихідні дані.

5. Повідомлення.

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

Керівництво системного адміністратора (системного програміста)

 

Цілі й завдання

Якщо програма більш-менш проста, користувач може встановити її собі на комп'ютер самостійно. Підтримувати її роботоспроможність, наприклад, виконати переустановку, якщо виникнуть які-небудь проблеми, він теж, як правило, у стані.

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

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

Керівництво системного адміністратора – програмний документ, що надає фахівцеві інформацію, необхідну для виконання цієї роботи.

В ЕСПД фахівець, подібний по обов'язках із сучасним системним адміністратором, називається системним програмістом, а адресований йому документ – керівництвом системного програміста.

Зміст документа

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

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

 

 

Отже, у керівництві системного адміністратора повинні бути викладені:

- призначення й область застосування програми (або комплексу);

- состав програми, основні принципи її функціонування;

- комплект поставки (якщо він не зазначений в окремому документі);

- системні вимоги для програми або її компонентів;

- краща черговість установки компонентів;

- процедура установки програми або кожного її компонента;

- порядок обов'язкового первісного настроювання програми;

- способи інтеграції встановлених копій компонентів між собою;

- інтеграція програми зі стороннім ПЗ, наприклад, із сервером БД;

- способи й періодичність контролю правильності роботи програми;

- порядок поточного обслуговування працюючих копій програми;

- порядок рішення всіляких допоміжних завдань;

- аварійні ситуації й способи їхнього усунення.

Чи є цей список тим вичерпним? Зовсім ні. Нерідко в керівництві системного адміністратора доводиться також описувати:

- користувальницький інтерфейс адміністративної консолі;

- утиліти командного рядка й синтаксис їхнього запуску;

- конфігураційні файли й правила їхнього написання;

- мова для складання керуючих скриптів.

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