История изменений

Документация будет прикручиваться к функциям и вообще разным блокам

Пусть прикручивается. Но... в виде отдельной цельной PDFки оно будет? Которую я могу полистать, поскакать с одной части на другую и даже (иногда и такое нужно бывает) распечатать для чтения в поезде?

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

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

Отдельная тема — описание стандартной библиотеки. Не думай, что «прикручивание к блокам» тебе его заменит. К примеру, в Qt Creator у меня работает автодополнение кода, есть всплывающие подсказки по всем классам и функциям. Но тем не менее, есть и связная справка, в которой эти же классы описаны последовательно.

Отдельная тема — связь с кодом на других языках.

Отдельная тема (и одна из первых) — общая характеристика продукта: под какими платформами работает среда, какие процессорные архитектуры поддерживаются и с какими компиляторами работа проверена. Понятно, что сишный кодогенератор даёт возможность поддержки кучи архитектур, и тем не менее, поддержку конкретного ARMv7, MIPS, а может, чем чёрт не шутит, и E2k, надо проверять отдельно. Когда Метапрог будет готов для продакшена, этот раздел должен быть одним из первых. Но на стадии пре-альфы его, конечно, написать не получится, да и не надо. Описание синтаксиса (блоки, связи) куда важнее для тех, кто будет решать, стоит ли им вообще с Метапрогом связываться.

Для меня важно услышать — будет ли в принципе такой документ, или ты хочешь отделаться «прикручиванием документации к блокам» в самой среде?

Документация будет прикручиваться к функциям и вообще разным блокам

Пусть прикручивается. Но... в виде отдельной цельной PDFки оно будет? Которую я могу полистать, поскакать с одной части на другую и даже (иногда и такое нужно бывает) распечатать для чтения в поезде?

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

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

Отдельная тема — описание стандартной библиотеки. Не думай, что «прикручивание к блокам» тебе его заметит. К примеру, в Qt Creator у меня работает автодополнение кода, есть всплывающие подсказки по всем классам и функциям. Но тем не менее, есть и связная справка, в которой эти же классы описаны последовательно.

Отдельная тема — связь с кодом на других языках.

Отдельная тема (и одна из первых) — общая характеристика продукта: под какими платформами работает среда, какие процессорные архитектуры поддерживаются и с какими компиляторами работа проверена. Понятно, что сишный кодогенератор даёт возможность поддержки кучи архитектур, и тем не менее, поддержку конкретного ARMv7, MIPS, а может, чем чёрт не шутит, и E2k, надо проверять отдельно. Когда Метапрог будет готов для продакшена, этот раздел должен быть одним из первых. Но на стадии пре-альфы его, конечно, написать не получится, да и не надо. Описание синтаксиса (блоки, связи) куда важнее для тех, кто будет решать, стоит ли им вообще с Метапрогом связываться.

Для меня важно услышать — будет ли в принципе такой документ, или ты хочешь отделаться «прикручиванием документации к блокам» в самой среде?