Создание документации

Создание документации в ispmanager Docs - важный процесс, который обеспечивает структурированное и понятное представление информации о продукте.  В этом разделе подробно описано создание статей и использование инструментов ispmanager Docs.

Создание статьи

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

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

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

Откроется форма для заполнения. В этой форме находятся следующие активные кнопки и поля.

• Удалить в корзину - функция Удалить в корзину предназначена для удаления статьи, которая больше не требуется. Она помогает очистить документацию от устаревшего или ненужного контента, отправляя его в специальный раздел Корзина;
• Опубликовать - кнопка Опубликовать используется для размещения текущей статьи в документации и делает ее доступной для пользователей. Это важный шаг, который позволяет распространять информацию среди всей аудитории;
• Предпросмотр - эта кнопка позволяет предварительно просматривать статью после внесенных изменений. Это полезно для убеждения, что документация выглядит корректно;
• Ревизии - раздел Ревизии позволяет вернуться к предыдущим версиям или исправлениям статьи. Это полезно в случае ошибочных изменений или если необходимо восстановить предыдущее состояние статьи. Ревизии помогают в управлении историей изменений в документации;
• Сохранить - нажмите эту кнопку, чтобы сохранить все внесенные изменения в статье. Это важно, чтобы не потерять текущую работу;
• Название - введите название статьи, используя цифры, кириллические и латинские буквы. Хорошо подобранное название поможет пользователям быстро найти нужную информацию;
• Родительская статья - выберите раздел, в котором будет размещена статья. Это поможет организовать документацию в логическом порядке;

• Ключевое слово - введите название статьи на транслите, используя только строчные латинские буквы и тире между словами. Это ключевое слово помогает при поиске и индексации статьи;

  Обратите внимание!

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

   

• SEO заголовок - введите заголовок в формате: название раздела в документации, за которым следует название статьи. Это помогает оптимизировать статью для поисковых систем;
• SEO описание - добавьте дополнительное описание статьи. Это также важно для SEO и улучшения видимости статьи в поисковых результатах.

Создание текстовых блоков

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

Heading - функция Heading используется для создания заголовков. Заголовки обычно используются для выделения ключевых разделов или частей документа. 

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

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

Создание разворачиваемого пояснения. Если требуется предоставить дополнительные детали или сделать информацию доступной по запросу, можно использовать функцию Spoiler. Нажмите на соответствующую кнопку.

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

Alert - выделение блока с желтым фоном и восклицательным знаком. Этот стиль применяется, чтобы выделить определенный блок текста.

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

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

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

Delimiter - разделительный элемент. Горизонтальная черта.

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

Code - опция Code предоставляет возможность вставки кода в документ. При выборе Code откроется меню, в котором можно указать формат кода, который  собирается использоваться (например, Bash, PHP, HTML). Либо поставить автоматический выбор нажав Auto language. После выбора формата введите код в соответствующем блоке. Это особенно полезно при документировании программных решений или предоставлении примеров кода.

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

Инструменты форматирования текста

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

Convert to - этот инструмент позволяет преобразовать выделенную строку в различные форматы. Можно сделать ее заголовком, выделить текст желтым фоном с восклицательным знаком, выделить текст сиреневым фоном или создать подпункты.

Bold - этот инструмент позволяет выделить текст жирным шрифтом, что делает его более заметным и выразительным.

Italic - этот инструмент позволяет сделать шрифт текста наклонным, придавая ему курсивный вид.

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

Underline - этот инструмент добавляет подчеркивание текста, выделяя его.

Inline code - этот стиль используется для вставки коротких строк кода в текстовом контексте, а не в виде отдельного блока кода. Это позволяет легко включать код в текст и подчеркивать его внимание.

Strikethrough - зачеркивает текст, обозначая, что он неактуален или изменен.

Marker - позволяет выделить текст желтым цветом, делая его более заметным.

Attributes - этот функционал позволяет задавать выбранному тексту HTML атрибуты style (для прописывания CSS стилей) и id.

Sub - создает подстрочный текст, который располагается ниже обычного текста.

Sup - создает надстрочный текст, который располагается выше обычного текста.

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

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

Отображение функционала в документации с правами администратора.

Отображение в общей документации.