ПО, ЭВМ и АСУ из Таможенного Союза

Информация о пользователе

Привет, Гость! Войдите или зарегистрируйтесь.

Список артефактов

Страница: 1

Сообщений 1 страница 6 из 6

1

  • Автор: Лис [Л]
  • Участник
  • Лис [Л]
  • Зарегистрирован: 2021-02-04
  • Приглашений: 0
  • Сообщений: 1027
  • Уважение: [+0/-0]
  • Позитив: [+0/-0]
  • Провел на форуме:
    5 дней 7 часов
  • Последний визит:
    2023-03-10 00:04:11

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

0

2

  • Автор: Лис [Л]
  • Участник
  • Лис [Л]
  • Зарегистрирован: 2021-02-04
  • Приглашений: 0
  • Сообщений: 1027
  • Уважение: [+0/-0]
  • Позитив: [+0/-0]
  • Провел на форуме:
    5 дней 7 часов
  • Последний визит:
    2023-03-10 00:04:11

Что-то люди не подтягиваются в тему.

Ну, для начала, нужны:
1) репозиторий с кодом реализации виртуальной машины
2) репозиторий с TeX-кодом-исходниками для .pdf-книжки, которая описывает эту виртуальную машину, принятые решения (руководство разработчика)
3) репозиторий с TeX-кодом-исходниками для .pdf-книжки, которая описывает работу с git (твойгит), сборку и вообще прочие методические указания по использованию (такая смесь руководства пользователя и руководства администратора, ну и немножно разработчика)
4) репозиторий с TeX-кодом-исходниками для .pdf-документа, спецификации бинарного формата выполняемого кода
5) репозиторий с TeX-кодом-исходниками для .pdf-документа, спецификации файлового формата для хранения кода на диске
6) репозиторий с TeX-кодом-исходниками для .pdf-документа, перечисляющего и описывающего все инструкции виртуальной машины
7) репозиторий с описанием синтаксиса языка ассемблера
8) репозиторий с методическими указаниями по написанию программ на ассемблере этой машины

Что-то нужно меньше, что-то больше. Возможно, что нужен сайт, на котором та же самая информация будет представлена в виде HTML
(и тогда возникает вопрос, так ли хорош TeX, или выбрать другой формат типа DocBook для того, чтобы писать тексты один раз и получать сразу и .pdf и HTML).

0

3

  • Автор: Евгений
  • Участник
  • Зарегистрирован: 2022-04-16
  • Приглашений: 0
  • Сообщений: 379
  • Уважение: [+0/-0]
  • Позитив: [+0/-0]
  • Провел на форуме:
    8 дней 13 часов
  • Последний визит:
    2023-10-01 23:46:28
Лис написал(а):

Что-то люди не подтягиваются в тему.

Ну, для начала, нужны:
1) репозиторий с кодом реализации виртуальной машины.

Как раз занимаюсь этим. Подойдет ли нам для проекта одна из этих лицензий?
The MIT License
Apache License 2.0
The Unlicense

0

4

  • Автор: Лис [Л]
  • Участник
  • Лис [Л]
  • Зарегистрирован: 2021-02-04
  • Приглашений: 0
  • Сообщений: 1027
  • Уважение: [+0/-0]
  • Позитив: [+0/-0]
  • Провел на форуме:
    5 дней 7 часов
  • Последний визит:
    2023-03-10 00:04:11
Евгений написал(а):

Как раз занимаюсь этим. Подойдет ли нам для проекта одна из этих лицензий?
The MIT License
Apache License 2.0
The Unlicense

Лично мне - да, подойдёт.
МихалНик предлагал делать отдельную лицензию проекта на русском языке при помощи российских юристов,
но это долго, и когда ещё будет...
А меня устраивает любая, которую я не сильно мучаясь смогу запихнуть в пакетный менеджер своей операционной системы.
Unlicense тут вызывает опасения (я её не часто там встречал), а MIT и Apache-2.0 это типовые лицензии и проектов с ними - гора,
было бы очень удобно.

0

5

  • Автор: Евгений
  • Участник
  • Зарегистрирован: 2022-04-16
  • Приглашений: 0
  • Сообщений: 379
  • Уважение: [+0/-0]
  • Позитив: [+0/-0]
  • Провел на форуме:
    8 дней 13 часов
  • Последний визит:
    2023-10-01 23:46:28
Лис написал(а):

2) репозиторий с TeX-кодом-исходниками для .pdf-книжки, которая описывает эту виртуальную машину, принятые решения (руководство разработчика)
3) репозиторий с TeX-кодом-исходниками для .pdf-книжки, которая описывает работу с git (твойгит), сборку и вообще прочие методические указания по использованию (такая смесь руководства пользователя и руководства администратора, ну и немножно разработчика)
4) репозиторий с TeX-кодом-исходниками для .pdf-документа, спецификации бинарного формата выполняемого кода
5) репозиторий с TeX-кодом-исходниками для .pdf-документа, спецификации файлового формата для хранения кода на диске
6) репозиторий с TeX-кодом-исходниками для .pdf-документа, перечисляющего и описывающего все инструкции виртуальной машины

Doxygen делает очень неплохую документацию из исходного кода. PDF и HTML в комплекте. Если изначально нацелиться на него и соответствующим образом
писать комментарии, то на выходе получится готовое руководство. Вот другие инструменты. Может есть какие-то предпочтения.

0

6

  • Автор: Лис [Л]
  • Участник
  • Лис [Л]
  • Зарегистрирован: 2021-02-04
  • Приглашений: 0
  • Сообщений: 1027
  • Уважение: [+0/-0]
  • Позитив: [+0/-0]
  • Провел на форуме:
    5 дней 7 часов
  • Последний визит:
    2023-03-10 00:04:11

Я знаю о существовании doxygen (и даже запускал его несколько раз), но никогда не видел проектов, хорошо продокументированных при помощи него. На качество документации влияет количество вовлечённых людей и суммарное время потраченное на проработку вопросов. Использование дополнительного инструмента снижает количество людей, которые будут участвовать, потому что инструмент надо изучать. Кроме того, сам инструмент неудобен - он сосредотачивается на абстракциях в коде (классах, методах), в то время как в документации должно быть больше абстракций - сценарии использования, требования, архитектура того как требования будут воплощаться в коде и много всего ещё (доказательства алгоритмов, например).
Пример хорошего инструмента для документирования - это stackoverflow. Он хорош тем, что много разных реальных людей задают вопросы, которые именно им непонятны. Структурирование массива вопросов там хромает (теги не вытягивают задачу, потому что между тегами нет навигации). Пара из wiki и q&a сайта это некое первое приближение того, что нужно.

Отредактировано Лис (2023-02-17 20:04:07)

0

Страница: 1