Интро

О тех.документации замолвите слово

Один из примеров превосходной документации, что мне попадались - это документация компании Atmel (линейка микроконтроллеров AVR, различные AppNotes и даже современные линейки МК серии AT SAM).

Например, даже в 2022г различные Application Notes серии AVRxxx созданные около 20лет назад остаются образчиком лаконичности и умения максимально понятно доносить информацию (возможно в английском для этого существует термин из одного слова).

А юзабилити (UI/UX?) документации на МК (Technical Reference Manual) обычно сочетается с простой и изяществом архитектурных решений (уверен что не я один подглядывал и черпал вдохновения у Атмела при проектировании SoC или её периферии 🙈).

Из более современных примеров документации хочу отметить “первый кремний” от Raspberry Pi Trading Ltd: микроконтроллер RP2040. Что хочу отметить: помимо интересных технических решений (архитектора и микроархитектура) полезных для как начинающих так и опытных чипмейкеров также хочется обратить внимание на типографику: например, способы представления тех же регистровых карт (100% автоматически генерируемых из мета-описания).

Ну и как вишенка на торте: даташит на RP2040 свёрстан на моём любимом Asciidoc 😍

❓А какие удачные примеры тех.документации попадались вам? И чем конкретно они отличны?

!!! todo: [ссылка на RP2040 datasheet (Raspberry Pi Trading Ltd)]

Вейвформы

Наследие

Этим тулом похоже рисовались временные диаграммы в доWAVEDROMовские времена (а точнее - привет из 80хх).

Хотя Dinotrace скорее симбиоз Wavedrom и GTKwave ибо на входе может принимать как VCD так и специально оформленные ASCII-форматы. Что интересно в репо до сих пор, хоть и нечасто, коммитятся фиксы и апдейты.

AsciiArt

Лучшая документация - самодокументируемый исходник.

Wavedrom конечно божественнен, когда надо в полиграфического качества PDF надо вставить вейвформу в SVG, но в HDL-исходник такое засунуть сложно, да и зачем? 🤔

Толи дело AsciiArt, которым еще деды пользовались, самое то для SaaD (sources as a docs) 🤘

А поможет с этой задачей вот этот тул (https://github.com/yne/vcd).

Wavedrom: десять оттенков серого

А вы знали, что Wavedrom поддерживает скины? Конечно туда можно добавлять свои экстравагантные цветовые решения (что наверное никто никогда не сделает), но что более интересно: там есть скин для людей с ограниченными возможностями цветовосприятия и/или для компаний, которые архивируют документацию в печатном виде на монохномных принтерах (да и для адаптации пдф к публикации в виде книги такой скин тоже полезен).

Кстати, оказывается есть WaveDromPy - переписанный на питон функциональный аналог оригинального WaveDromJS. Поддержка скинов там тоже реализована, но в самих используемых исходниках скинов видимо где-то ошибка - неправильно отрисовывает (возможно проблема решается просто перетаскиванием обновленных файлов скинов из оригинального проекта).

Схемы

verilog -> svg

💾 https://github.com/nturley/netlistsvg

При оформлении технической документации часто приходится вставлять скетчи/куски схемы и хочется использовать не скрин из EDA/CAD, а что-то красивое, векторное, версионируемое. Как GraphViz, но только не для диаграмм, а для схем.

И похоже есть прекрасное начинание для такого инструмента, принимающего на вход специально оформленный JSON (который можно выписать из Yosys), а на выходе отдающий SVG:

yosys -p "prep -top my_top -flatten; write_json output.json" input.v

netlistsvg  output.json [-o output.svg] [--skin skin_file]

PS: Проекту хочется пожелать процветания и повторения триумфа Wavedrom‘овской рисовалки эпюр.

Приблуда для вязки жгутов

💾 https://github.com/formatc1702/WireViz

• Версионирование мета-описания в человеко-понятном YAML-формате
• Возможность цветового кодирования проводов по DIN/IEC
• Возможность указывать сечение и генерить BOM (Bill of Materials)
• Питонячий опенсорс с возможностью кастомайзинга и допилинга

Symbolator

💾 https://github.com/kevinpt/symbolator

Еще одна полезная утилита, которая в какой-то степени поможет автоматизировать создание документации для IP-cores. Есть инструкция.

• На вход принимает VHDL и Verilog
• На выходе генерит PNG, SVG, PDF, PS или EPS
• Возможность внутри исходника через прагмы задавать шины, стили выводов и определять группировки по функциональному назначению
• Питоняшность 🙃

Картинки

Ссылки на инструменты и стандарты по рисованию диаграм и векторных картинок для технической документации:

• drawio - есть онлайн и офлайн версия, также есть плагины для гугл-доков
• yEd
• ditaa
• plantUML
• graphViz / DOT
• LibreOffice Draw
• kroki.io
• TikZ и прочие TeX плагины
• asciiart 🤪

---

• Graphviz онлайн-рендеринг

Bytefield

Генерилка картинок из описания битовых полей регистров: bytefield-svg умеет в asciidoc, но изначально автор вдохновлялся версией для LaTeX.

Еще есть похожая штука - для удобного описания формата пакетов: PacketDiag

Переводческое

Краудсорсинговый проект помощи с переводом на другой язык специфической терминологии (есть много веток: от астрологии до кулинарии).

Быстрые ссылки на ветку по электронике:

• 🇬🇧 → 🇷🇺
• 🇷🇺 → 🇬🇧

PS: не сказать прям, что проект живой (судя по активности в ветках) - может кто-то натыкался на аналогичные более обитаемые порталы ❓

LateX

Datasheet

• LaTeX-шаблон для оформления даташитов

ГОСТ

• Шаблоны для документов по отечественным ГОСТам: https://github.com/Korogodin/NSLReport