Создание инструкций. Оформляем контент в Confluence

  Здесь мы собрали минимально необходимую информацию для оформления статьи в Confluence.

Создание новой страницы

Чтобы создать новую страницу, выберите категорию, пространство и раздел. Так, создаваемая страница будет связана с выбранным разделом. 

Например:

• Дисциплина → Архитектурный BIM → Коммерция → Подразделы → Создать новую страницу
• Сервисы → Учебный центр BIM → Развитие → Создать новую страницу
  
  

Нажмите значок «Создать» в правом верхнем углу.

Выберите шаблон или используйте пустую страницу.

 

Создание нового раздела с вложенными страницами

Создайте новую страницу — это будет страница раздела. Внутри неё создавайте страницы статей.

Перейдите в режим редактирования на странице нового раздела, в верхнем меню выберите «Вставить прочий контент»

Выберите в списке «Другие макросы», через поиск найдите «Отображение дочерних»

Вставьте макрос, чтобы все эти вложенные страницы были видны на странице раздела. 

Оформление заголовка

Введите заголовок страницы.  

Общие правила составления заголовков 

Заголовки страниц должны быть уникальными. Это важно для поисковой системы.

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

Используйте общепринятые термины и аббревиатуры. 

Структурируйте текст, придерживайтесь подхода «От общего к частному». Не дублируйте название предыдущего уровня, если логическая цепочка не обрывается.

Добавьте к заголовку дополнительные слова или аббревиатуру, если в разных подразделах у вас должны находиться инструкции с одинаковыми названиями.

Разместите уточнение в конце заголовка, чтобы в начале находилось уникальное название. Соблюдение этого правила сделает работу с каталогом удобнее.

Вставка оглавления

Вставьте оглавление, если в тексте больше двух-трёх абзацев.

Прежде всего оформите заголовки блоков/рубрик текста через встроенную систему заголовков (это необходимо для использования макроса). 

Выберите макрос «Оглавление» через функцию «Вставить прочий контент» в верхнем меню. 

Задайте уровни заголовков, которые должны отображаться, в настройках. Чтобы увидеть результат, используйте кнопку «Предварительный просмотр».

Если вы хотите закрепить оглавление при прокрутке страницы, используйте макрос Easy Heading Macro. 

Выберите «Вставить прочий контент» → «Другие макросы» и введите название в поисковую строку.

Реализацию можно посмотреть прямо в этой статье или в учебных инструкциях к курсам «Технология проектирования в Revit»: Написать заявку в поддержку

Если вам нужно закрепить оглавление при прокрутке страницы, а также добавить все ссылки из статьи, то используйте макрос «Плавающее содержание».

Выберите «Вставить прочий контент» → «Другие макросы» и введите название в поисковую строку.

Реализация в режиме просмотра:

Реализацию также можно посмотреть в учебных инструкциях к курсам «Технология проектирования в Revit»: Проверить и исправить дубликаты семейств

Форматирование текста

Используйте в инструкции простые предложения. Разделяйте текст для лучшего восприятия. Соблюдайте правило: в одном абзаце - 4-5 предложений. В предложении должно быть 8-10 слов. Если слов больше, разделите на два предложения.

Выполняйте основной текст стилем «Абзац», для деления текста применяйте систему заголовков. 

 Или воспользуйтесь инструментом «Разметка страницы». 

 
Используйте также разделительную линию, чтобы зонировать текст. 

Форматируйте тест при помощи встроенных инструментов.

Используйте списки при перечислениях, вам доступны два вида.

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

• Пример
• Пример
• Пример

Нумерованный список, когда позиции списка имеют заданную последовательность.

1. Действие 
2. Действие
3. Действие
   
   

Выделяйте важное в тексте. 

Чтобы выделить текст (особенно, если в текстовом блоке больше 3-4 слов), не рекомендуется использовать капслок, красный цвет и курсив: ЧТО БЫ НИ СЛУЧИЛОСЬ, НИ В КОЕМ СЛУЧАЕ НЕ НАЖИМАЙ ЭТУ КЛАВИШУ! 

Обычно текст, оформленный подобным образом, читатели игнорируют или просматривают бегло. Текст, набранный основным шрифтом, прочтут с большей вероятностью. Для выделения блока лучше использовать эмодзи или символы: ☝ или специальные блоки. Можно также использовать слова: Внимание! Совет и др.

Введите систему маркировки для типовых элементов и на протяжении всего текста придерживайтесь правил этой маркировки. 

Например:

• полужирный шрифт — для описания названий элементов интерфейса и кнопок

• прописная буква и кавычки (ёлочки) — для описания команд, вводимых пользователем

• курсивный шрифт — для терминов или привлечения внимания к определенным словам (предложения, набранные курсовом плохо читаются)

• рамка — для оформления фрагментов кода

• маркеры и иконки — для типовых блоков: путь к файлу, порядок действий, важная информация
  
  

Используйте макрос Info, чтобы выделить текст в виде блока.

Оформляйте содержательные ссылки на другие ресурсы. 

Соблюдайте авторское право. Указывайте название источника заимствования, если этого материала больше 20% в отношении объема вашей статьи, или вы использовали изображения из внешней среды.

Изучите макросы из основного списка и блока «Другие макросы». Это поможет вам автоматизировать задачи по организации контента. Вы сможете создавать структурированный и удобный для восприятия текст.

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

Если вы не обновили статью, то все внесенные изменения сохранятся в виде неопубликованных. 

Визуализация

Добавляйте изображения к тексту. Для этого используйте наиболее удобный вам способ.

Перетащите объект в поле страницы в режиме редактирования. 

Следите за названием изображений, если вы добавите на страницу новое изображение с таким же названием, то старое изображение автоматически заменится на новое.

Воспользуйтесь инструментом меню «Вставить изображение», если вы работаете с набором изображений.

Отроется окно с функций «Загрузить файлы».  После загрузки файлов, вы можете выбрать нужные для вставки. Нажмите кнопку «Вставить».

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

Окно «Свойства изображения» имеет два режима: эффекты и описание. 

В режиме «Описание» вы можете добавить подпись для изображения, которая будет появляться при наведении на него:

Задайте изображениям содержательные названия, тогда они будут попадать в выдачу по поиску. Это также поможет вам, если одно и то же изображение нужно разместить на разных страницах. Не придётся дублировать изображение несколько раз.

По умолчанию в каталоге сохраняется название изображения, включая формат и путь. Это можно увидеть в режиме редактирования при наведении на изображение:

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

Сначала загрузите файл с компьютера на страницу Confluence, с которой вы планируете подгружать файл в макрос. После этого вы можете удалить отображение файла на странице, но он останется во вложении. Чтобы увидеть вложения страницы, в режиме чтения нажмите на значок «Скрепка».

Вам откроется 

Файл PDF

Перетащите PDF-документ с компьютера в пространство Confluence. Удалите его на странице, при этом он сохранился во вложении страницы.

Вставьте макрос PDF.

Выберите страницу, с которой должен подгружаться файл PDF. Поскольку это единственный подходящий файл для макроса, он сразу отображается в блоке «Имя файла». Если на странице несколько таких файлов, то нужно выбрать нужный из выпадающего списка.

Результат в режиме редактирования:

Результат в режиме просмотра:

Файл PDF отображается через внутренний интерфейс, пользователь может перелистывать страницы.

Аудио- и видеофайлы

Перетащите аудио- и видеофайлы с компьютера в пространство Confluence. Удалите их на странице, при этом они сохранились во вложении страницы.

Вставьте макрос Multimedia.

Выберите страницу и файл для отображения на странице публикации.

Результат в режиме просмотра:

Добавление меток

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

При создании новых разделов и страниц обязательно следует проставлять метки их принадлежности: 

• к дисциплине (разделу проектирования): АР, КР, ЭОМ и т.д.
• к инструментам и ПО: Revit, Civil 3D, Family Manager, BIM Inspector, PIKTools и т.д. 
• к сервису: BIM-поддержка , BIM-координация, Фабрика семейств, Учебный центр. 

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

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

В диалоговом окне введите названия необходимых меток и нажмите кнопку «Добавить».  Если метка с таким именем уже существует, она появится в меню автоподстановки. Если название новое, оно добавится в каталог.

Общие правила наименования:

• Давайте меткам понятные, содержательные имена. или общепринятые сокращения.  Допустимо использовать кириллицу и латиницу. 
• Не ориентируйтесь на различия по прописным и строчным буквам, замена на строчные  происходит автоматически. 
• По возможности ставьте слова в им. падеже и единственном числе. 
• Добавляйте нижнее подчёркивание или дефис в словосочетаниях, иначе отдельные слова добавятся в каталог как разные метки. 

 
Изучите каталог меток, прежде чем создавать новую метку. Возможно, что-то похожее уже существует. 

Общие правила размещения меток:

Чтобы не придумывать новые правила, используйте уже разработанную систему. Посмотрите правила Группы BIM-поддержки Метки инструкций. 

Если вы создаёте для своего раздела собственные правила, то следуйте общим рекомендациям: 

• Не создавайте множество меток, по которым можно найти только одну страницу.  Учитывайте все алгоритмы поиска: через наименование страницы происходит конкретизация поиска
  

• Добавляйте метки к странице по принципу «от общего к частному»