Подготовка технической документации *

Мини Революция в Word: Word: теперь при вставке скопированного текста применяется форматирование документа.

После многих лет обращений от пользователей, Microsoft наконец-то добавили функцию изменения стандартных настроек копирования.

Теперь не придется беспокоиться о том, что скопированный из интернета текст испортит ваш документ.

Для внесения изменений перейдите во вкладку "Файл", выберите "Параметры", затем "Дополнительно". В разделе "Вырезать, копировать и вставить" найдите опцию "Вставить из других программ" и измените значение.

Если интересуетесь темой ИИ и нейросетей, здесь я публикую разбор свежих моделей, статей и гайдов, кладешь полезной информации. 

#word

Приходит потенциальный клиент к разработчику…

— Мне бы сайт разработать! Можете сказать, сколько это будет стоить?
— А проектная документация у вас есть?
— Не-а.
— Она нужна для оценки. Попробуйте сходить к проектировщику интерфейсов. Возвращайтесь с проектной документацией — и я оценю разработку.

И клиент идёт к проектировщику интерфейсов. Например, ко мне.

— Мне бы сайт спроектировать! Можете сказать, сколько это будет стоить?
— А задание на проектирование у вас есть?
— Не-а. Только не говорите, что опять надо к кому-то идти?!
— Нет. Давайте с вами созвонимся такого-то числа во столько-то — и я за час соберу у вас все необходимые сведения для составления этого задания. Дальше вы проверите, нигде ли я не ошибся — и если всё ок, то я смогу оценить проектирование.

Вот примерно так я обычно и создаю документы под названием «Функциональные требования» (ФТ). По ним я могу оценить объём работ по проектированию. Вот вам видеоролик, в котором показываю пример такого документа и рассказываю о некоторых нюансах его подготовки.

Недавно набрёл на интересный сайт с описанием системы документирования. Речь идёт не о системе подготовки документации, а именно о принципах и подходах в документировании. Меня просто заворожила простота, ясность и лаконичность как самой системы, так и её изложения. Прочитать можно буквально за полчаса.

Уверен чтение будет интересно и полезно всем, кто сталкивается с необходимостью заниматься документированием проекта, библиотеки, фреймворка.

There is a secret that needs to be understood in order to write good software documentation: there isn’t one thing called documentation, there are four.

They are: tutorials, how-to guides, technical reference and explanation. They represent four different purposes or functions, and require four different approaches to their creation. Understanding the implications of this will help improve most documentation - often immensely.

https://documentation.divio.com

Эксперт Джон Джаго назвал два проекта с открытым исходным кодом, у которых разработчиками собрана и представлена исключительная техническая документация, включая высокую детализацию кода и архитектуры. Это esbuild и Redis.

По мнению Джаго, через файлы README, журналы изменений, архитектурные документы и комментарии к коду оба эти проекта объясняют свой дизайн таким образом, чтобы даже новичок может понять в кодовой базе, где что находится, как что-то делается и почему это делается именно так. Он порекомендовал разработчик, желающим лучше документировать свой код и архитектуру программного обеспечения, брать для примера эти проекты.

Преимущества хорошей документации:

• экономия времени на работы с кодом, особенно если работаете командно, не нужно дополнительно объяснять всю кодовую базу каждому разработчику;

• такой проект с открытым исходным кодом с большей вероятностью получит поддержку со стороны и, следовательно, продолжит своё существование даже после того, как автор больше не сможет его поддерживать;

• прошлые ошибки и решения, которые подвергались сомнению, записаны, что не позволяет случайно повторно привести к проблеме, которую помогло решить прошлое решение;

• приложение или библиотеку смогут использовать больше людей, поскольку меньшему количеству из них придётся во всем разбираться самостоятельно;

• это помогает структурировать ваше мышление и выявить недостатки. Когда вы пишете, вам необходимо чётко обдумывать и записывать то, что вы думаете, и это выявляет потенциальные проблемы.

5 полезных расширений VScode для работы с документацией

1. Draw.io Integration
   
   Хорошо подходит для работы со сложными диаграммами: сперва можно создать диаграмму в десктопной версии Draw.io, а потом доработать ее в VScode с помощью расширения Draw.io Integration.

2. Quarto
   
   Quarto — крутая штука для работы с документацией под R, Python, Julia и Observable. Расширение Quarto для VScode поможет редактировать и рендерить QMD-файлы. В нем есть режим предварительного просмотра, который позволяет менять код документа и одновременно просматривать результат.

3. Jupyter
   
   Jupyter — один из самых популярных фреймворков для создания заметок, особенно в Python. Кстати, Jupyter классно работает вместе с документацией Quarto для Python. Расширение VScode Jupyter интегрирует заметки Jupyter в редактор VScode и поддерживает ipynb-файлы.

4. Markdown All in One
   
   С расширением Markdown All in One удобно редактировать документацию в формате Markdown. Оно располагает два окна рядом: редактор кода и тут же результат.

5. Mermaid
   
   Mermaid особенно полезен, если вам нужно создать структуру кодовой базы или динамическую диаграмму. В VScode есть два расширения для работы с файлами Mermaid — Mermaid Preview и Markdown Preview Mermaid Support.

Этот топ расширений составил автор этой статьи, а ее перевод читайте у нас в блоге.

Для решения одной задачи мне потребовалось найти закрепленное в стандартах определение понятия "информация". Из тех, что я нашел, мне наиболее понравилось:

знания относительно фактов, событий, вещей, идей и понятий, которые в определённом контексте имеют конкретный смысл.

Если верить Википедии, статье на Хабре и статье в научном журнале, это определение дано в ISO/IEC 2382:2015 «Информационные технологии. Словарь».

В оригинале этого стандарта я, действительно, вижу похожее определение информации:

knowledge concerning objects, such as facts, events, things, processes, or ideas, including concepts, that within a certain context has a particular meaning

Но, в адаптации этого стандарта под ГОСТ, я обнаружил только трактовку в контексте каких-то финансовых учреждений:

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

Притом, что иные определения в этом ГОСТ даны в общем контексте и довольно близко по смыслу. Кто-нибудь понимает, что это за нафиг и откуда вылезли финансовые учреждения?