Cтраница 1
Страница руководства документирует формат файлов, создаваемых и обрабатываемых программой ARCHIVE. Нередко эта информация не предоставляется пользователю, порой из-за того, что является внутренней, которую пользователь не должен знать, порой из-за путаницы между сокрытием информации и секретностью. Файл в значительной степени является внешним объектом, тем, с чем от времени могут производиться действия другими инструментальными средствами. Поэтому важно, чтобы форматы файлов были четко документированы, в особенности для программ записи файлов. [1]
Страницы руководства должны быть пронумерованы до того, как Вы сможете составить окончательное оглавление. Посколь -, ку оглавление еще не составлено, Вы не знаете, сколько оно, займет страниц. [2]
Страница руководства краткая, но исчерпывающая. В ней говорится о некотором очевидном применении и приводится конкретный пример, который потенциальные пользователи могут испробовать, чтобы: а) убедиться в правильности эксплуатации программы COPY и б) усилить понимание данного документа. [3]
Приведем страницы руководства для примитивов, которые должны сопутствовать упомянутым объявлениям. Заметим, что эти страницы отличаются от страниц руководства для программ двумя существенными моментами: в разделе ОБРАЩЕНИЕ демонстрируется, как объявляется примитив, а не как он вызывается, и, кроме того, имеется новый раздел ВОЗВРАТ, в котором описываются значения, возвращаемые функциям, или параметры, записанные в параметрах VAR функциями или процедурами. Любые другие побочные эффекты, такие как изменение состояния файла, оговариваются также в разделе ФУНКЦИЯ. Здесь опущен раздел ПРИМЕР, поскольку в этой книге приведено множество примеров использования примитивов. [4]
В эту страницу руководства введен новый интересный раздел - объявление об известных недостатках. Это позволяет документировать программу в том состоянии, в котором она находилась в день написания страницы руководства, не прибегая к вымыслам о том, как она должна выполняться и предупреждать пользователя о проблемах, которые в противном случае могут быть упущены. [5]
В этой странице руководства предусматриваются заранее даже недостатки. С другой стороны, она является средством предупреждения о том, что программист не должен стремиться вводить недозволенные символы - с помощью простой программы они не будут распознаны. [6]
На этот раз страница руководства представлена раньше программы, что весьма полезно как начало любого проекта - она заставляет сразу концентрировать внимание на том, в какой форме должен предстать перед пользователем конечный результат. [7]
В заключение представим страницу руководства для программы FORMAT. Она содержит разумный набор команд, однако, несомненно, возможны и некоторые другие. [8]
Другим преимуществом предварительной записи страницы руководства является возможность точно определить то, что должно быть выполнено. Часто бывает трудно узнать, когда следует заканчивать программистский проект, поскольку всегда найдется еще одна дорогая чьему-либо сердцу деталь, которую, возможно, стоит добавить. Но раз уже с помощью программ выполняется то, о чем говорится в справочном листе, трудно оспаривать тот факт, что работа сделана. Из всех известных факторов, влияющих на продуктивность работы программиста ( кроме природных способностей), единственным наиболее важным является качество данной в начале разработки спецификации: чем она точнее и однозначнее, тем лучше. [9]
Важно и то, как оформлена страница руководства. Внешняя простота помогает читателю. Если руководство выглядит внешне сложным, у чита теля создастся о нем превратное мнение еще до того, как он его прочтет. Строгое соблюдение способа оформления текста определяет расположение материала на странице и облегчает чтение. [10]
Здесь мы встретились именно с тем случаем, когда страница руководства действительно окупается полностью. Все особенности, которые обсуждались на пути создания окончательного варианта TRANSLIT, теперь можно аккуратно подытожить. Квадратные скобки [ . . , ] в разделе ПРИМЕНЕНИЕ указывают на дополнительные возможности. [11]
ЭВМ типа IBM, за год пролистывают около 100 тыс. страниц руководств. [12]
Если Вы будете копировать руководство на копировальной машине, убедитесь, что страницы руководства подобраны в определенной последовательности. Поскольку при копировании страницы обычно переворачиваются лицевой стороной вниз, напишите номера страниц ярко-синим карандашом на оборотной стороне каждой страницы. [13]
Первое русское руководство по теоретической механике Скорняко-ва - Писарева [1] вышло в 1722 г. На 36 страницах руководства излагаются в весьма лаконичной форме семь проблем, содержащих описания простых машин и иллюстрирующие их работу числовые примеры. Главная ценность книги как практического руководства заключается в препорциях вычитания - соотношениях между силами и расстояниями, которыми следует руководствоваться при конструировании простых машин. Указанные соотношения устанавливаются на элементарных числовых примерах, не сопровождаются никакими доказательствами, ни даже простыми логическими рассуждениями. [14]
ВЫПУСКАЙТЕ СПИСОК ТЕКУЩЕГО СОДЕРЖАНИЯ Периодически ( раз в год или после каждых четырех-пяти изменений) рассылайте всем держателям руководства список. В этом списке будет перечислена каждая страница руководства и указана дата на этой странице. Этот метод аналогичен методу с выпуском новых оглавлений, описанному ранее. [15]