Навигация:  Справочная информация > Модульные проекты > Планирование модульных проектов

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

Важное примечание:

Большинство правил, описанных здесь, является самым важным для действительно модульных систем справки, созданных с со слиянием при запуске. В проектах, использующих слияние при компиляции, они не настолько принципиальны для вашего вывода. Даже в этом случае, хорошо спланировать ваши проекты этим путем. Потом Вы всегда имеете свободу переключиться к слиянию при запуске, если хотите, и ваши проекты будут также иметь лучшую и более логическую структуру, которая проще для обработки в конечном счете.

Решите, какой модуль является вашим главным модулем:

Даже при том, что каждый проект Help & Manual может содержать так много модулей, как Вы хотите, Вы должны всегда управлять каждой модульной системой справки с одним главным проектом, иначе Вы сойдете с ума, пробуя следить за всеми, и ошибки рано или поздно почти гарантируются. Вы можете многократно использовать модули в разных модульных системах справки, но тогда они должны быть полностью отдельными системами с собственными главными модулями.

Подмодули могут также содержать собственные подмодули. Однако, вероятно проще избегать использовать эту возможность, если ваш проект не является действительно большим. Если все компоненты модуля вашей системы справки ясно видимы в главном проекте, это может помочь сохранять вещи яными. И так как Вы можете вставить модули как подмодули модулей в пределах главного проекта, нет действительно никакой неотложной потребности вкладывать модули в пределах подпроектов.

Хорошо хранить ваши дочерние проекты модуля в подкаталогах вашего главного проекта модуля на вашем жестком диске. Это не принципиально, но тогда Вы имеете еще одну структуру, которая отражает фактическую структуру вашего проекта. Это делает проект проще для понимания, особенно для новых членов группы, которые присоединяются к проекту после того, как Вы начали работать.

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

Ваша структура справки должна отражать структуру вашего приложения:

Дизайн системы справки должен всегда отражать архитектуру приложения, для которого она сделана. Если ваше приложение состоит из нескольких модулей, Вы должны создать отдельный модуль проекта Help & Manual для каждого модуля программы. Вы должны также организовать ваши модули так, чтобы Вы нуждались в минимальном числе ссылок между модулями.

Это применяется, даже если Вы работаете в группе и хотите назначить индивидуальные модули на разных авторов. Если один автор собирается работать с частью справки для одной части вашего приложения и другой частью справки для другой части, это заставляет создавать для этого автора проектный модуль, который содержит две части. Однако, это было бы плохой идеей, потому что это создаст нелогичную структуру справки, которая отличается от структуры вашего приложения, и может позже вызвать проблемы управления и ссылок.

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

Минимизируйте ссылки между модулями:

Каждый модуль должен быть независимым и полон сам по себе, насколько возможно. Он должен содержать всю информацию, описывающую модуль вашего приложения, для которого был построен.

Если Вы используете слияние при запуске, особенно важно удостовериться, что контекстно-зависимые разделы справки, нужные вашим модулям програмы, предоставлены соответствующими модулями справки. Вызвать контекстные разделы справки через модули возможно, но это - четкий рецепт для беспорядка и проблем, потому что Вы никогда не можете убедиться, что модули, содержащие разделы, всегда на месте. (Если Вы используете слияние при запуске, Вы должны всегда делать ваши контекстно-зависимые запросы непосредственно к модулям, содержащим разделы. Запросы к всплывающим разделам не направляются из главного модуля к дочерним модулям.)

Ссылки к главному модулю никогда не проблема, потому что он всегда присутствует, но ссылки между модулями, и от главного к дочерним модулям должны быть сведены к абсолютному минимуму. Если Вы должны создать межмодульные ссылки, Вы должны быть абсолютно уверены, что целевой модуль будет всегда присутствовать, когда пользователь запускает справку. Альтернативно, используйте A-ссылки, чтобы удостовериться, что ссылки к несуществующим модулям отобразят подходящий альтернативный раздел.

Предпримите шаги, чтобы избежать двойных ID раздела и контекстных чисел:

При слиянии при компиляции двойные ID раздела и числа справочного контекста в модулях вызовут отказы ссылки и другие ошибки в ваших файлах справки. Help & Manual может предотвратить дубликаты только в пределах единственного проекта, таким образом Вы должны предпринять шаги, чтобы предотвратить дубликаты в ваших модулях самостоятельно. Больше деталей смотрите в Управление ID и контекстными числами в Работа с модульными системами справки.

Избегайте вкладывать модули:

Вы можете вложить модули (то есть сделать дочерние модули других модулей, или в Содержании главного модуля, или в пределах дочерних модулей непосредственно), но хорошо свести это к абсолютному минимуму, если возможно. Каждый дополнительный уровень вложенности - еще один дополнительный уровень сложности и еще один источник потенциальных пользовательских ошибок. Простая структура проще для управления.

Избегайте смешивания слияния при компиляции и при запуске:

Как правило, Вы не можете смешивать слияние при запуске и при компиляции в одном проекте. Например, когда Вы компилируете ваш главный проект со слиянием при компиляции, он должен включать дочерний проект, который содержит проекты, которые слиты при запуске - это не будет работать.

Наоборот не проблема: Если главный проект компилируется со слиянием при запуске, он может содержать дочерние проекты, которые содержат собственные дочерние проекты, слитые при компиляции, потому что эти проекты будут включены в единственный проект вывода. Будьте внимательный, делая это, однако, потому что очень просто потерять дорожку структуры и создать проблемы, которые очень трудно решить.

Всегда помещайте все ваши выходные файлы в тот же каталог:

Это должно быть абсолютным правилом. Справка HTML в особенности имеет немного раздражающих ошибок, которые делают почти невозможным вызвать файлы из справки, которые не находятся в том же каталоге, как файл справки. Даже если ссылки к другим каталогам, кажется, работают на вашем тестовом компьютере, они подведут на компьютерах очень многих пользователей, так что не используйте их.

Всегда помещайте все ваши файлы справки и любые внешние файлы, которые Вы должны вызвать, в том же каталоге. Это - единственный способ избежать проблем и иметь систему справки, которая всегда работает.

См. также:

Работа с модульными системами справки