Методика й стиль викладу
Найважливіші методичні вимоги до теоретичної частини керівництва програміста - логічність і послідовність викладу. Зокрема, у тексті обов'язково повинні бути дотримані наступні правила:
При введенні нового поняття ми опираємося тільки на ті поняття, які були введені раніше явно або вважаються свідомо знайомими читачеві. Як у підручнику математики.
У читача ніколи не повинне виникати відчуття, що автор плодить сутності без потреби. Введення кожного поняття повинно бути чимось обґрунтовано.
Основна вимога при описі окремих об'єктів - повнота опису кожного з них. На відміну від посібника користувача, при складанні якого в принципі можна розраховувати на догадливість читача, що подивиться на інтерфейс і сам розбереться, керівництво програміста описує досить неочевидні речі. І хоча від програміста можна чекати більшої догадливості, чим від користувача, заповнювати недолік інформації йому доведеться аналізом вихідного тексту, а якщо він доступний, то тестуванням «чорного ящика» і відладником. Це набагато більш довгий процес, ніж «блукання» по меню й діалоговим вікнам.
При описі об'єктів особлива увага варто приділяти наступним аспектам:
Що обов'язково повинно передувати створенню й використанню об'єкта.
Які побічні ефекти звертання до об'єкта.
Особливості інтерпретації об'єктом переданих йому даних.
Де «фізично» (у якому файлі, у якій бібліотеці) перебуває об'єкт.
Бажано по кожному об'єкті привести приклади використання, невеликі фрагменти коду, що демонструють:
створення об'єкта (якщо перед використанням його необхідно створити);
передачу об'єкту вхідних даних;
одержання вихідних даних і їхню інтерпретацію.
Опис об'єктів можна винести в окремий том або документ за назвою «Довідник програміста». Гарна думка — зробити його гіпертекстовим.
Між теоретичною частиною й довідником по об'єктах корисно помістити невеликий розділ, у якому розглядається приклад невеликого, але повноцінного, з погляду використовуваної платформи, додатка. Приклад повинен бути таким, щоб читач зміг самостійно цей додаток відтворити, налагодити й запустити. Очевидно, для цього спочатку все це повинен проробити хтось із авторів керівництва програміста.
Типова структура
Структура керівництва програміста, зафіксована в ДСТ 19.504-79, така:
Призначення й умови застосування програми.
Характеристика програми.
Звертання до програми.
Вхідні й вихідні дані.
Повідомлення.
Враження корисної в сучасних умовах така структура не робить. Скоріше, за цим планом може бути описаний окремий об'єкт, допустимо, функція або клас. Скласти типову структуру керівництва програміста на все випадку життя ми не візьмемося.
2. Керівництво системного адміністратора (системного програміста) Цілі й завдання
Якщо програма більш-менш проста, користувач може встановити її собі на комп'ютер самостійно. Підтримувати її роботоспроможність, наприклад, виконати переустановку, якщо виникнуть які-небудь проблеми, він теж, як правило, у стані.
Складними, у тому числі, серверними й мережними програмними продуктами доводиться займатися кваліфікованим фахівцям, системним адміністраторам. Більше того, у багатьох компаніях співробітникам заборонено встановлювати на своїх робочих місцях програми за своїм розсудом. Навіть прості програми там ставить тільки системний адміністратор.
В обов'язки системного адміністратора також входить підтримка працездатності програм, використовуваних у рамках тих або інших систем. Ця діяльність може полягати в періодичній перевірці логів, резервному копіюванні даних, вимірах продуктивності, усуненні різних технічних проблем.
Керівництво системного адміністратора - програмний документ, що надає фахівцеві інформацію, необхідну для виконання цієї роботи.
В ЕСПД фахівець, подібний по обов'язках із сучасним системним адміністратором, називається системним програмістом, а адресований йому документ — керівництвом системного програміста.