Я действительно выделяю ПМИ среди прочих документов. И изучение любой новой системы начинаю с ПМИ. Это важнейший инструмент обеспечения качества продукта. Не формальный, творческий. В него надо включать не всё подряд, а именно то, что важно. Но!!! всё, что важно, в него нужно включить)) Да еще необходимо включить так, чтобы заказчик понял всё, что написано. Включим лишнее — получим бюрократию. Не включим важное — можем получить некачественный продукт. Сделаем документ непонятным — получим никому не нужную формальную процедуру испытаний.
И, честно говоря. Ни разу в жизни у меня не получилось ПМИ, которым был бы доволен:)
В рамках испытаний проверяются не только функциональные фичи. Поэтому и ПМИ должна содержать методику проверки не только фич. Наличие документации является фичей? Соответствие требованиям ИБ является фичей? Лицензионная чистота является фичей? Инфраструктура развертывания является фичей?
В примере с Васей Вы предлагается ввести обязательное требование, чтобы все фичи реализовывались долго? Если так, их тоже надо проверять в рамках испытаний. Например, в ПМИ можно ввести пункта: С момента появления требования до его реализации должно пройти не менее 20 рабочих дней. Проверить очень легко. Если сделали быстрее, испытание не считается пройденным.
Мне кажется, устойчивость к регрессам — важный аспект системы. И желательно, чтобы он проверялся и при создании, и при доработке информационной системы.
Скажем, нужно добавить проверку для формочки. Вполне логично, если ПМИ будет содержать проверку на наличие регрессионного теста, и вполне логично проверить, чтобы тест срабатывал успешно. В более сложных случаях нужно что-то еще придумывать. Хотя употребленное Вами слово "работоспособность" вполне хорошее, я бы его заменил на "качество".
Не совсем понимаю. Скажем, в моменте система работает. А через неделю (или, скажем, через час), когда в нее внесут правки пусть функции отваливаются? Или испытания — это способ убедиться, что мы, наконец, поняли, что хочет Заказчик? Т.е. после ввода системы в постоянную эксплуатацию ПМИ архивируем для Счётной палаты?
Тут встает вопрос этики. Но, работая в этой сфере (госы) более 20 лет, могу сказать, что случаи, когда документацию по системе можно оценить хотя бы на три балла (из пяти) крайне редки. Если Вы скажете, что Ваш опыт говорит об обратном, я буду счастлив и скажу, что хочу в Советский Союз.
ПМИ — это как раз пример документа, который очень часто делают для галочки — своеобразный чек-лист, который надо сначала убедить заказчика принять, а потом убедить расписаться в каждом квадратике. Потому что любая сложная информационная система содержит разноаспектные требования. Задача разработать методику, которая позволит их действительно проверить и потом не допустить регресса информационной системы при эксплуатации и развитии — уж точно не простая.
Что такое автоматизировать создание паспорта — не совсем понял.
Документация — моя профессия, я не могу себя ее лишать. Речь идёт не просто об улучшении, а об изменении порядка качества. В целом, об изменении отношения к документации.
Много работая в данной сфере, я попытался сформулировать текущую ситуацию. Чтобы вылечить человека, надо чтобы он понял, что он болен. Чтобы захотел изменить ситуацию. Чтобы заказчик захотел получить не объем макулатуры а то, что ему поможет при работе с системой.
Таблицы — вопрос решенный. Вот пример таблиц в Asciidoc:
Можно и многострочные заголовки делать. И вложенные таблицы. И даже повторять на каждой странице только номера столбцов.
Процесс тоже более менее понятен (при наличии нативного экспорта в doc/docx/odt):
Вопрос в инструменте, который поможет вносить обратные правки. Что это такое может быть? Вот тут хорошо бы порассуждать.
Само сравнение, как справедливо указано здесь, сделать просто.
Понятно также, что мы работаем с текстом, т.е. поиском найти, куда вносить изменение, можно довольно быстро. Но явно тут можно найти что-то более красивое и не очень сложное.
Кроме Pandoc я, честно говоря, других конвертеров не знаю. Pandoc имеет смысл только для помощи в ручной конвертации документа. На выходе Pandoc не выдает качественного документа, поддерживающего всю разметку Asciidoc (точнее Docbook, потому что прямое применении Pandoc к Asciidoc — это кошмар), а также рамки и тому подобную ерунду. Pandoc + доводочные костыли — так себе решение — прыжок без парашюта. И как бы Pandoc не развивался, он всё прогоняет через AST, т.е., вспоминая Форда, машина может быть любого цвета, если этот цвет — чёрный. Отсюда и вывод о необходимости именно нативного легко расширяемого конвертера.
Насколько я понимаю Вашу мысль, хорошо бы сделать обратный конвертор, который после внесения правок автоматизирует их утрамбовку обратно в Asciidoc (автоматическая генерация коммитов — было бы верхом красоты). Но документ в doc/docx/odt получается из объединения многих Asciidoc-документов. А часто (в нашем случае), изменения надо вносить в исходный код, если, например, в документе размещены атрибуты REST-интерфейса в табличной форме. Скорее нужно говорить о том, чтобы легко понять, куда вносить правки. Думаю, это тоже решаемый вопрос при использовании нативного конвертера с сохранением определенной мета-информации в результирующем документе. Ну и отсюда уже можно думать что-то на тему автоматических коммитов.
Вариант хорош. И обязательно нужен, но для сравнения выпущенных версий документов. Скажем, согласовали какую-то инструкцию. Потом выпустили новую версию и можем указанным Вами образом сравнить. Pdf-документы так удобно сравнить не получится.
А вот для работы над документацией этот вариант просто очень громоздок. Насколько проще работать с таким видом. Тут и изменения в коде, и связанные изменения в документации, причём сразу во всех файлах.
Аналогично через автоматизацию Word можно сделать всё, но сложно или долго. А в Asciidoc простая директива include.
Вопросы же простые. Мы делаем документ или документацию? Наша документация будет жить вместе с продуктом или сделали и забыли?
1. Проблема не в том, чтобы файл создать. А в том, чтобы содержание этого файла можно было настраиваемым образом использовать в других документах. Этого у Word нет.
2. С версионированием и контролем изменений у Word беда. Кто тот или иной текст засунул в документацию? В связи с какими изменениями в коде засунул? Хотя сравнение документов (именно конечных форматов) — прекрасная функция
3. Ну и с автоматическим созданием тоже всё не очень хорошо. Asciidoc, Markdown, rst создается из чего угодно (это же текст), а вот Word далек не из чего угодна. Сама задача сложнее
Спасибо за комментарий. На самом деле, вот уже с месяц пытаюсь сделать нативный конвертер из Asciidoc в open document. Такое ощущение, что получается. Тогда человекочасы не понадобятся.
По крайней мере Reveal-презентации Decktape прекрасно переводит в pdf. Это, конечно, растры, но с заданным разрешением, поэтому в нормальном качестве. Причем как во варианте с анимацией, так и во варианте без нее
Нет, они прекрасно переводятся в html, который можно выложить куда угодно, или для конференций часто лучше сделать pdf. Там, конечно, нет въезжающей и выезжающей анимации, но зато не слетит
Мы используем Asciidoc, но суть не меняется. На всех конференциях и в полиграфии — самое то. За последние два года не сделал ни одной презентации в Powerpoint и аналогах. Коллеги используют Markdown и тоже с отличным результатом. И Latex, как мы видим, прекрасен. Отличная статья на правильную тему. Спасибо автору
Поправьте меня, если не прав, но в Office365 групповая работа организована чуть по-другому. Слияние изменений происходит при сохранении, а не как в Google Docs в режиме on-line. Хотя, возможно Microsoft уже добился одновременной работы в режиме on-line.
Тоже считают, что asciidoctor в настоящий момент — лучшее решение. Но справедливости ради необходимо отметить, что (1) есть не менее популярный Shinx (https://github.com/sphinx-doc/sphinx), (2) есть проекты, которые пытаются и довольно успешно компенсировать недостатки маркдауна (https://github.com/foliant-docs/foliant) и (3) на солнце (в asciidoctor'е) тоже есть пятна
Вопрос тут прагматичнее. Научился делать что-то в plaintext’е — сможешь грузить это на рынок килограммами. Приведу по памяти цитату Генри Форда: «Чтобы достичь успеха, необходимо научиться делать что-то полезное в больших количествах и по низкой цене».
Процесс непрерывной интеграции, о котором в том числе говорится в статье в отношении презентации, более чем отлично может отрабатывать ситуации с недоступными ресурсами, а заодно и с многими другими возможными нарушениями качества, которые можно поймать автоматически: орфография, висячие предлоги в заголовках и т.п. Направление стрелочки, конечно, попутать можно, впрочем, как и Северную Корею с Южной.
Если говорить в целом об организации совместной работы, то система контроля версий и непрерывная интеграция — это другой порядок эффективности, чем Sharepoint. Проблема в том, что часто нужна функциональность Powerpoint’а. Ну и тот же git, да ещё и с Travis’ом, да ещё и с Maven’ом освоить значительно сложнее, чем Sharepoint.
Я действительно выделяю ПМИ среди прочих документов. И изучение любой новой системы начинаю с ПМИ. Это важнейший инструмент обеспечения качества продукта. Не формальный, творческий. В него надо включать не всё подряд, а именно то, что важно. Но!!! всё, что важно, в него нужно включить)) Да еще необходимо включить так, чтобы заказчик понял всё, что написано. Включим лишнее — получим бюрократию. Не включим важное — можем получить некачественный продукт. Сделаем документ непонятным — получим никому не нужную формальную процедуру испытаний.
И, честно говоря. Ни разу в жизни у меня не получилось ПМИ, которым был бы доволен:)
В рамках испытаний проверяются не только функциональные фичи. Поэтому и ПМИ должна содержать методику проверки не только фич. Наличие документации является фичей? Соответствие требованиям ИБ является фичей? Лицензионная чистота является фичей? Инфраструктура развертывания является фичей?
В примере с Васей Вы предлагается ввести обязательное требование, чтобы все фичи реализовывались долго? Если так, их тоже надо проверять в рамках испытаний. Например, в ПМИ можно ввести пункта: С момента появления требования до его реализации должно пройти не менее 20 рабочих дней. Проверить очень легко. Если сделали быстрее, испытание не считается пройденным.
Прямо хорошо всё)
Мне кажется, устойчивость к регрессам — важный аспект системы. И желательно, чтобы он проверялся и при создании, и при доработке информационной системы.
Скажем, нужно добавить проверку для формочки. Вполне логично, если ПМИ будет содержать проверку на наличие регрессионного теста, и вполне логично проверить, чтобы тест срабатывал успешно. В более сложных случаях нужно что-то еще придумывать. Хотя употребленное Вами слово "работоспособность" вполне хорошее, я бы его заменил на "качество".
Не совсем понимаю. Скажем, в моменте система работает. А через неделю (или, скажем, через час), когда в нее внесут правки пусть функции отваливаются? Или испытания — это способ убедиться, что мы, наконец, поняли, что хочет Заказчик? Т.е. после ввода системы в постоянную эксплуатацию ПМИ архивируем для Счётной палаты?
Тут встает вопрос этики. Но, работая в этой сфере (госы) более 20 лет, могу сказать, что случаи, когда документацию по системе можно оценить хотя бы на три балла (из пяти) крайне редки. Если Вы скажете, что Ваш опыт говорит об обратном, я буду счастлив и скажу, что хочу в Советский Союз.
ПМИ — это как раз пример документа, который очень часто делают для галочки — своеобразный чек-лист, который надо сначала убедить заказчика принять, а потом убедить расписаться в каждом квадратике. Потому что любая сложная информационная система содержит разноаспектные требования. Задача разработать методику, которая позволит их действительно проверить и потом не допустить регресса информационной системы при эксплуатации и развитии — уж точно не простая.
Что такое автоматизировать создание паспорта — не совсем понял.
Документация — моя профессия, я не могу себя ее лишать. Речь идёт не просто об улучшении, а об изменении порядка качества. В целом, об изменении отношения к документации.
Много работая в данной сфере, я попытался сформулировать текущую ситуацию. Чтобы вылечить человека, надо чтобы он понял, что он болен. Чтобы захотел изменить ситуацию. Чтобы заказчик захотел получить не объем макулатуры а то, что ему поможет при работе с системой.
Таблицы — вопрос решенный. Вот пример таблиц в Asciidoc:
Можно и многострочные заголовки делать. И вложенные таблицы. И даже повторять на каждой странице только номера столбцов.
Процесс тоже более менее понятен (при наличии нативного экспорта в doc/docx/odt):
Вопрос в инструменте, который поможет вносить обратные правки. Что это такое может быть? Вот тут хорошо бы порассуждать.
Само сравнение, как справедливо указано здесь, сделать просто.
Понятно также, что мы работаем с текстом, т.е. поиском найти, куда вносить изменение, можно довольно быстро. Но явно тут можно найти что-то более красивое и не очень сложное.
Кроме Pandoc я, честно говоря, других конвертеров не знаю. Pandoc имеет смысл только для помощи в ручной конвертации документа. На выходе Pandoc не выдает качественного документа, поддерживающего всю разметку Asciidoc (точнее Docbook, потому что прямое применении Pandoc к Asciidoc — это кошмар), а также рамки и тому подобную ерунду. Pandoc + доводочные костыли — так себе решение — прыжок без парашюта. И как бы Pandoc не развивался, он всё прогоняет через AST, т.е., вспоминая Форда, машина может быть любого цвета, если этот цвет — чёрный. Отсюда и вывод о необходимости именно нативного легко расширяемого конвертера.
Насколько я понимаю Вашу мысль, хорошо бы сделать обратный конвертор, который после внесения правок автоматизирует их утрамбовку обратно в Asciidoc (автоматическая генерация коммитов — было бы верхом красоты). Но документ в doc/docx/odt получается из объединения многих Asciidoc-документов. А часто (в нашем случае), изменения надо вносить в исходный код, если, например, в документе размещены атрибуты REST-интерфейса в табличной форме. Скорее нужно говорить о том, чтобы легко понять, куда вносить правки. Думаю, это тоже решаемый вопрос при использовании нативного конвертера с сохранением определенной мета-информации в результирующем документе. Ну и отсюда уже можно думать что-то на тему автоматических коммитов.
Вариант хорош. И обязательно нужен, но для сравнения выпущенных версий документов. Скажем, согласовали какую-то инструкцию. Потом выпустили новую версию и можем указанным Вами образом сравнить. Pdf-документы так удобно сравнить не получится.
А вот для работы над документацией этот вариант просто очень громоздок. Насколько проще работать с таким видом. Тут и изменения в коде, и связанные изменения в документации, причём сразу во всех файлах.
Аналогично через автоматизацию Word можно сделать всё, но сложно или долго. А в Asciidoc простая директива include.
Вопросы же простые. Мы делаем документ или документацию? Наша документация будет жить вместе с продуктом или сделали и забыли?
2. С версионированием и контролем изменений у Word беда. Кто тот или иной текст засунул в документацию? В связи с какими изменениями в коде засунул? Хотя сравнение документов (именно конечных форматов) — прекрасная функция
3. Ну и с автоматическим созданием тоже всё не очень хорошо. Asciidoc, Markdown, rst создается из чего угодно (это же текст), а вот Word далек не из чего угодна. Сама задача сложнее
Вопрос тут прагматичнее. Научился делать что-то в plaintext’е — сможешь грузить это на рынок килограммами. Приведу по памяти цитату Генри Форда: «Чтобы достичь успеха, необходимо научиться делать что-то полезное в больших количествах и по низкой цене».
Процесс непрерывной интеграции, о котором в том числе говорится в статье в отношении презентации, более чем отлично может отрабатывать ситуации с недоступными ресурсами, а заодно и с многими другими возможными нарушениями качества, которые можно поймать автоматически: орфография, висячие предлоги в заголовках и т.п. Направление стрелочки, конечно, попутать можно, впрочем, как и Северную Корею с Южной.
Если говорить в целом об организации совместной работы, то система контроля версий и непрерывная интеграция — это другой порядок эффективности, чем Sharepoint. Проблема в том, что часто нужна функциональность Powerpoint’а. Ну и тот же git, да ещё и с Travis’ом, да ещё и с Maven’ом освоить значительно сложнее, чем Sharepoint.
О, и preview тоже есть. https://asciidoctor.org/docs/asciidoctor-revealjs/#basic-presentation-with-speaker-notes