Если инструкция на 2-3 страницы, то конечно не очевидно, а если документ 500 страниц и ещё по ГОСТу, то жизненно необходимо

Наверное, у Романа не возник такой вопрос, если бы документ был по госту

ГОСТ выносим за скобки)

Не знаю, кого как, а меня от этих «рис. 1» аж подташнивает.

Возможно потому, что вспоминается универ, курсач, денег нет 😀

А еще могут сказать " у вас там на рисунке ось х не подписана, а на какой странице я не помню"

Нумерация удобна, если на рисунок или таблицу надо сослаться в тексте или где-то ещё.

Сравните запрос на изменение доки от коллег: «Нужно добавить параметр в таблицу 8» VS «Нужно добавить параметр в таблицу, которая на 13 странице в таком-то разделе»

Тут возможны варианты.

Ссылки можно сделать якорями.

А второй момент - это польза для писателя, а не для читателя

Иной раз лучше и повторить скриншот, чем заставлять пользователя переходить по ссылке или листать до нужного рисунка.

Надо смотреть конкретную документацию

К слову: давным давно где-то (в каком-то «учебнике» для дизайнеров) видела , что меленько на полях повторяется скриншот со ссылкой на нумерованный рисунок.

Ахахха)

Смотря где. Если это веб или что-то, где последовательное чтение не важно, а рисунок идёт сразу под ссылкой, нумерация не нужна. А если это научный труд или книга, нумерация рисунков, как и нумерация заголовков полезна, так как вы читаете такой материал последовательно с первой и до последней главы.

Ориентация по документу

Простите, лучше поздно, чем никогда (это я про себя).

1) Критерий истины - практика. Если разработчики, для которых это описание предназначено, не вкуривают, значит, информации не достаточно. И все доводы автора-разработчика про краткость, сестру таланта, побоку.

2) У горячо любимого всеми Тома Джонсона черным по белому прописано, что есть API Reference, а есть conceptual topics. Так что дополнительная информация в описании API - вполне нормально.

3) Я в описание API обычно всегда добавляю схему последовательности запросов с привязкой к "бизнес"-логике. Более того, для некоторых случаев мы пишем примеры сценариев использования запросов с учетом особенностей клиента (мобильное приложение, веб-приложение, банкомат и т.п.)
На одном API Reference интеграцию можно запустить, но это будет несколько дольше и мучительнее.

Спасибо огромное! Звучит здраво

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

у lokalise под статьями смайлики есть, туда можно было бы еще поле для текста добавить, может. Но три смайлика на выбор вообще норм и нетрудно

да, тоже вариант 👍

ищу технического писателя на ГПХ на блокчейн проект #wanted_tw . Задача - вести проектную документацию. Свободный график, можно как подработка к основной работе. Писать мне в личку. EasyChain в Москве. Можно в любом городе но по московскому времени

Юлия, добрый день. Укажите пожалуйста город и название компании.