room topic changed to Technical writing: Вопросы по написанию техдокументации, включая вопросы и ответы на SO [stackoverflow] [документация]

room topic changed to Technical writing: Вопросы по написанию техдокументации, включая вопросы и ответы на SO [stackoverflow] [technical-writing]

@soon Речь же идет о документации для технических специалистов (т.е не для маркетинговых целей и т.п.)?

@soon впрочем, очевидно, что да. Это техническая спецификация должна быть. Думаю, стоит начать с того, чтобы посмотреть документацию к самым успешным аналогичным API

@soon поскольку область строгая, то стоит уделить внимание формулировкам, особенно модальным глаголам (нужно, желательно, предполагается, гарантируется и т.п.) Вот есть примерный свод правил про их использование на английском, но можно и на русском составить что-то подобное: tools.ietf.org/html/rfc2119

@soon вот этот образец мне очень нравится структурой сайта. Она помогает не потеряться в документации (которая чаще выглядит как портянка текста без разметки) matrix.org/docs/api/client-server/#!/-registration

@NickVolynkin, отлично, спасибо

@soon вообще начать написание стоит с того, чтобы ответить на следующие вопросы:

1. Кто заказчик документа? (т.е. кто инициировал процесс и определяет готово-не готово).

2. Кто клиент документа? Т.е. кто это будет читать (это совсем необязательно заказчик). В частности для клиент—сервера это может быть либо своя команда, которая пишет обе части, либо другие команды, которые сами по себе пишут, например, клиенты к нашему серверу

Клиент=целевая аудитория

3. Ну и в чем цель, хотя бы кратко определить.

и 4. Можно написать некоторый мета-документ, т.е. правила по тому, как мы будем писать документ. Это как раз о чем вы спросили — утвердить стандарт.

room topic changed to Technical writing: Обсуждаем написание техдокументации, включая вопросы и ответы на SO [stackoverflow] [technical-writing]

@NickVolynkin это сделано при помощи этого инструмента:

swagger.io

можете сравнить вашу ссылку с демо-примером: petstore.swagger.io/#!/store/getInventory

@AndreyBakharev о, спасибо. Отличная штука.

Кстати, есть интересный пример документации. Что-то вроде учебника по обработке сигналов и дискретному преобразованию Фурье: jackschaedler.github.io/circles-sines-signals/index.html Написано довольно хорошо, на мой взгяд. Как вам? Что можно было бы улучшить?

@NickVolynkin ясно, спасибо.

@AndreyBakharev насколько я понял, это для REST-сервисов? Есть аналог для чего-то более низкоуровнего, чтобы можно было также красиво побайтово расписать запрос / ответ? Пытался играть с их редактором - ругается при добавлении кастомных параметров, вместо, скажем, in, required и т.д. Может быть это регулируется какой-то схемой, но я ее не нашел.

@soon я сам его еще не смотрел, просто знаю что есть такой ) Etki вроде упоминал его как-то, про остальные сказать не могу