Комментарии 4
hsto.org/webt/eu/mu/tu/eumutuftauqkp1panbo6xtanf7e.png
Вы вводите определение «режим Coherence» которое стараетесь дальше использовать (тут же).
Предположим я первый раз вижу вашу программу — ничего не знаю о режиме coherence а первый абзац этого листа я даже прочитал — но как обычно через строку, и ничего оттуда не усвоил…
Дальше мне в тексте встречается это понятие «режим coherence». — и я не зная, что это дословным поиском по тексту пытаюсь найти определение… И тут выясняется — в вашем определении, эти слова даже рядом не стоят! Т.е. я найду, что угодно — но не описание, что же это за режим такой…
Суть: Если вы вводите какое то понятие, посвящаете ему целый абзац текста, используете его в дальнейшем — заголовок абзаца должен называться в точности этим понятием — т.е. абзац должен быть назван «Режим coherence» и выделен красным текстом — а то что это «объединение windows blabla» — можно или оставить в названии абзаца мелким текстом черед дефис или перенести в суть определения (середину абзаца)… Таким образом у вас определение оказывается и в оглавлении и выделяется жирно красно при поиске. Либо на крайний случай это понятие должно быть как то выделено в тексте в месте где оно определяется — что бы оно хотя бы поиском как то однозначно находилось.
Вы вводите определение «режим Coherence» которое стараетесь дальше использовать (тут же).
Предположим я первый раз вижу вашу программу — ничего не знаю о режиме coherence а первый абзац этого листа я даже прочитал — но как обычно через строку, и ничего оттуда не усвоил…
Дальше мне в тексте встречается это понятие «режим coherence». — и я не зная, что это дословным поиском по тексту пытаюсь найти определение… И тут выясняется — в вашем определении, эти слова даже рядом не стоят! Т.е. я найду, что угодно — но не описание, что же это за режим такой…
Суть: Если вы вводите какое то понятие, посвящаете ему целый абзац текста, используете его в дальнейшем — заголовок абзаца должен называться в точности этим понятием — т.е. абзац должен быть назван «Режим coherence» и выделен красным текстом — а то что это «объединение windows blabla» — можно или оставить в названии абзаца мелким текстом черед дефис или перенести в суть определения (середину абзаца)… Таким образом у вас определение оказывается и в оглавлении и выделяется жирно красно при поиске. Либо на крайний случай это понятие должно быть как то выделено в тексте в месте где оно определяется — что бы оно хотя бы поиском как то однозначно находилось.
Не согласен с требованием выносить режим в заголовок абзаца, при этом теряется исходная идея task-топика, то есть подхода «от задачи». Режим же здесь — средство выполнения задачи, он вторичен. Другое дело, что определен он в самом деле не сильно явно — тут согласен. Если уж используется термин «режим Coherence» — так и определен он должен быть именно в таком виде.
Ну и маленькая реплика от нормоконтроля: «Чтобы переключиться из режима „Окно“ в Coherence...» — всё же стоит использовать одинаковые подходы в именовании режимов — либо везде в кавычках, либо везде без них.
Ну и маленькая реплика от нормоконтроля: «Чтобы переключиться из режима „Окно“ в Coherence...» — всё же стоит использовать одинаковые подходы в именовании режимов — либо везде в кавычках, либо везде без них.
Что первично и что вторично в документации определяется совсем не этим. Если вы многократно ссылаетесь на определение а задачу описали лишь в одном месте — значит определение у вас важнее задачи в рамках структуры вами же написанного текста. Хотя тут еще вопрос. А нужно ли вообще вводить это определение? действительно ли оно что то экономит в объяснении — а не запутывает. Ключевая фраза объяснения определения — не сильно длиннее самого определения.
А вообще — все это лишние знания… Любой нормальный человек способный к анализу текста, просто интуитивно напишет хорошую документацию, прочитав за свою жизнь «десять условных других хороших документаций»… а если способностей нет — то не напишет, сколько в него не долби, как они пишутся… Нужно просто в рамка проекта найти такого человека — и задача решена…
А вообще — все это лишние знания… Любой нормальный человек способный к анализу текста, просто интуитивно напишет хорошую документацию, прочитав за свою жизнь «десять условных других хороших документаций»… а если способностей нет — то не напишет, сколько в него не долби, как они пишутся… Нужно просто в рамка проекта найти такого человека — и задача решена…
Спасибо большое за то, что делитесь своим опытом. Ваш подход тоже можно использовать. Термины также можно подробно описывать (и раскрывать) в справочных топиках или в словаре, о них будет отдельно рассказано в следующих частях «руководства».
Зарегистрируйтесь на Хабре, чтобы оставить комментарий
Вредные советы: как правильно писать техническую документацию? Часть вторая