Как-то в разнобой посты делаю, однако хотел закончить серию про доку. В частности как правильно ее делать?

Мой опыт такой: я сделал документацию, которая кажется мне полезной, краткой и вообще мне должны дать премию за нее. Когда же я по своей же документации начал что-то делать, оказалось что она вообще нихера не помогает. Натыкался на такое, как минимум раза 3.

И вот очередная мудрость от меня, как писать крутую доку. Топ 3 фишки, которые вам помогут.
👉 После написания, представляете что вы обделены разумом (в моем случае это представить очень легко) и по свой доке пытаетесь что-то сделать, не отходя от того, что вы написали. Получилось? Если да, то вы либо себя наебали, либо с первого раза сделали крутую доку. Если не получилось, дописываете и повторяете процедуру.

👉 Если ваша дока это инструкция с кучей шагов, очень круто помогает добавление валидации, после каждого шага. Например, разраб вызвал нужный скрипт. У него должна быть возможность проверить, что все отработало как нужно. Во-первых, это поможет убедиться что все ок, во-вторых, если что-то пошло не так, вам сразу напишут про конкретный шаг, где все сломалось.

👉 Банально, но, добавляйте ссылки на чат или имя конкретного человека к кому можно пойти с вопросом, если что-то не понятно. Сэкономите кучу времени тому кто захочет это использовать. Я часто натыкался на такое, ты встреваешь на каком-то моменте, а потом еще полчаса ищешь, а к кому вообще идти с этим.