Author's guide

Зачем этот проект

Мы независисый проект и идея построить открытые карты профессий — путь от новичка до уверенного специалиста, собранный из первоисточников и практики. Мы библиотекари, а не лекторы: не пересказываем документы своими словами, а говорим точно, какие главы прочитать и что после этого сделать руками. Материалы бесплатны и открыты (CC BY-SA) — навсегда; имя автора остаётся в истории каждой принятой правки.

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

Анатомия хорошей статьи

1. ЗАЧЕМ. Первый абзац одним-двумя предложениями честно отвечает «зачем тратить на это время» — конкретно, без общих слов. Он же показывается в поиске, поэтому до 155 знаков.
2. Суть. Объяснение как мастер напарнику: числа, марки, главы нормативов («глава 1.7 ПУЭ», а не «нормативная документация»). Если для задачи есть стандартная программа или прибор — назовите его по имени и скажите, зачем он.
3. Ссылки. Курированные и ранжированные: обязательные и рекомендуемые — двумя группами. Где тема регулируется — первоисточник (Норматив); где нет — лучший качественный материал, честно помеченный. Типы разобраны ниже.
4. Закрытие по пользе. Теория заканчивается самопроверкой [!ПРОВЕРЬ] — вопросами, которые заставляют думать, а не вспоминать. Практический навык — заданием: цель, что понадобится, шаги, самопроверка по нормативу. Ничего «для галочки»: разделу нечего дать — его не должно быть.
5. Безопасность. Везде, где работа касается напряжения, давления, высоты или газа — блок [!ОПАСНО]. В рабочих профессиях плохой совет калечит; это главный критерий проверки любой правки.

Три «нельзя»

1. Не выдумывать ссылки. Нет уверенного источника — оставьте пробел и напишите об этом в правке или автору. Одна фальшивая ссылка разрушает доверие ко всей странице.
2. Не пересказывать норматив вместо ссылки на него. Пересказ устаревает и врёт; наша ценность — привести человека к первоисточнику и показать, что именно там смотреть.
3. Не копировать чужие тексты. Всё здесь открыто под CC BY-SA — класть можно только то, что вправе распространяться свободно. Своими словами — можно и нужно.

Как живёт статья

Любой зарегистрированный читатель может предложить правку прямо на странице статьи. Правку проверяет эксперт профессии — практик с подтверждённым опытом; принятая правка становится вечной записью в открытой истории статьи с именем автора: ничего не теряется и не переписывается задним числом. Ошибка — не страшно: откат — это просто новая запись в истории. Публикация новых профессий и глав — за администратором.

Вы — Эксперт: как это работает

Эксперт — практик, которому открыто редактирование своих профессий (раздел Admin в меню). Шесть вещей, которые стоит знать в первый день:

1. Ваша зона — ваши профессии. Редактировать напрямую можно статьи профессий, к которым вам открыт доступ. В остальных вы предлагаете правки как читатель — тем же способом, с той же страницы статьи.
2. Очередь правок. Бейдж «Правки» в админ-меню — предложения читателей к вашим профессиям. Смотрите сравнение «Рядом», принимайте то, что улучшает статью. Комментарий при отклонении увидит автор правки — пишите его человеку, а не «для протокола». Если очередь ждёт дольше двух дней, придёт одно письмо-напоминание.
3. Ваш труд защищён. Первая же ваша правка «замораживает» статью: никакой импорт или LLM-черновик её не перезапишет. Каждое изменение — вечная запись в истории статьи; откат — просто новая запись. Ошибок можно не бояться.
4. Новая профессия или глава. «Программа» — конструктор: добавляйте главы и статьи, перетаскивайте, переименовывайте двойным кликом. «Импорт» — загрузите пак профессии (.zip) или вставьте YAML: сначала предпросмотр, без подтверждения ничего не записывается. Всё рождается черновиком — читатели его не видят.
5. Ваш опыт — главное, LLM — лишь ускоритель черновика. Кнопка «Экспорт» на странице профессии в конструкторе отдаёт карту паком — обычными YAML/Markdown-файлами; тем же паком она возвращается через «Импорт» с предпросмотром. Работайте с файлами как удобно: офлайн, в своём редакторе — а рутинную заготовку, если хотите, можно сгенерировать с помощью LLM по готовым промптам из репозитория (tools/). Платформа относится к этому спокойно: LLM экономит время на черновой работе, но качества не делает. Сверить со стандартами, убрать лишнее и добавить то, что даёт только живая практика, способен только специалист — именно на это стоит тратить ваше время, и именно это отличает хорошую карту. Поэтому любой импорт ложится черновиком и публикуется только после проверки человеком.
6. Публикация. Когда материал готов, поставьте статус «На проверке» — опубликует администратор. Это последний рубеж качества, а не недоверие.

Типы ссылок

Тип отвечает на вопрос «что это». Один тип на ссылку. Принцип — тип по делу: где тема регулируется, ставим первоисточник (Норматив); где нет — лучший качественный источник, честно помеченный.

Standard

Официальный обязательный документ: ГОСТ, ПУЭ, ПТЭЭП, СП, СНиП, НАКС, РД, приказы, а также международные IEC / ISO / ASME / EN / DIN. Спина контента — где тема регулируется, ссылаемся на первоисточник, а не на пересказ.

Book

Учебник, справочник, руководство — систематическое изложение темы (справочник электрика, учебник по сварке). Когда нужна глубина и контекст, а не одна норма.

Documentation

Документация производителя: даташит, техпаспорт, руководство по эксплуатации, каталог. Привязана к конкретному изделию — особенно важно для КИПиА (датчик, ПЛК, реле). Это паспорт прибора, а не норматив и не учебник.

Course

Структурированная программа обучения: онлайн-курс, ДПО, учебный центр, видеокурс. Целая программа, а не один материал; часто платная.

Video

Видеоразбор или демонстрация — YouTube, запись вебинара. Когда показать важнее, чем описать: монтаж, приёмы, работа прибором.

Article

Статья, разбор, объяснение — habr-стиль, экспертный блог. Хорошо объясняет тему простым языком, дополняя норматив.

Software

Программа или веб-сервис, которым работают: Modbus Poll, UaExpert, Wireshark, онлайн-калькулятор, конфигуратор. То, что запускают, а не читают.

Tool

Физический инструмент или материал для практики — ссылка, где приобрести (мультиметр, указатель напряжения, набор для пайки). Для практических заданий: «что понадобится и где взять».

Заметка к ссылке

Необязательная тихая строка под ссылкой — «что именно смотреть»: глава, разделы, минуты. Для документа на 400 страниц это разница между «прочитал нужное» и «закрыл вкладку». Пример: «только гл. 1.7, разделы 1.7.50–1.7.60»; для видео — «с 12-й минуты».

Маркеры

Маркер — вторая ось, поверх типа. У ссылки может быть ноль или несколько; маркер не меняет тип и не влияет на порядок.

EN

Источник на английском, когда у материала нет качественного русского аналога. Английский — международный язык техники: так мы честно берём лучшую мировую практику (US/IEC/ASME, даташиты) и помечаем, что материал не на русском. По умолчанию язык русский — без бейджа.

Текстовые блоки

Цветные блоки помогают выделить смысл — опасность, важный факт, совет. Вставляются в три шага:

1. На новой строке нажмите кнопку цитаты (❞ на панели редактора) — или просто наберите > в начале строки.
2. Первым внутри цитаты впишите маркер — например [!СОВЕТ]. Заглавными, в квадратных скобках с восклицательным знаком.
3. На той же строке, сразу после маркера, напишите текст блока.

Важно понимать: в самом редакторе это останется обычной цитатой с текстом «[!СОВЕТ] …». Цвет, иконка и подпись появятся уже на опубликованной странице статьи. Маркеров ровно пять (ниже); ставьте по делу, не для украшения.

цитата → [!ОПАСНО] текст блока…

цитата → [!ВАЖНО] текст блока…

цитата → [!СОВЕТ] текст блока…

цитата → [!ПРИМЕР] текст блока…

цитата → [!ПРОВЕРЬ] текст блока…