Comments 50
А почему статья названа «для программиста»?
Для команды — да. Но не для программиста.
Для команды — да. Но не для программиста.
Потому что задания для других участников команды — оставлены за кадром.
Интерфейс (визуальная часть) — не программеру, а дизайнеру.
Третий этап написания ТЗ — вообще не работа программиста.
Сопровождение документации — а тут прогеры при чем?
Все остальное — по сути общая инфа для команды. Но не полная т.к. рассмотрена лишь часть документации.
Третий этап написания ТЗ — вообще не работа программиста.
Сопровождение документации — а тут прогеры при чем?
Все остальное — по сути общая инфа для команды. Но не полная т.к. рассмотрена лишь часть документации.
Кажется, в тексте статьи не хватает полужирного начертания.
Возможно. =)
Выделение жирным упрощает чтение текста по диагонали.
Выделение жирным упрощает чтение текста по диагонали.
Вы, возможно, удивитесь, но статья — не ТЗ, и писать ее следует по несколько другим правилам.
Ага, гусиным пером и от руки, как писали лучшие авторы: Пушкин, Толстой, Достоевский. Почему бы не использовать современные возможности для достижения выразительности. Жирный шрифт не только упрощает чтение по горизонтали, но и заостряет внимание на важных с точки зрения деталях, которые могут быть упущены или посчитаны незначительными чтецом. В разговоре мы используем интонацию, паузы, жесты, почему стоит от этого отказаться при печати статей?
Проблема не в том, что вы используете выделение — просто не следует им злоупотреблять. Также следует разнообразить его — кроме полужирного начертания есть и курсивное.
Если уж серьезно к делу подходить, то каждое начертание для своей цели. Например, названия элементов интерфейса всегда выделяются жирным, а примеры текстовых сообщений — жирным курсивом.
Вы можете показать пример такого оформления?
Есть список формальных правил для оформления?
Есть список формальных правил для оформления?
Я специально написал — «например». Каждая организация выбирает свой стиль исходя из поставленных задач.
Есть на эту тему и ГОСТы, но название/номер что-то сразу не найти.
Есть на эту тему и ГОСТы, но название/номер что-то сразу не найти.
ГОСТ 19.106-78 Требования к программным документам, выполненным печатным способом.
ГОСТ который последний раз пересматривался в 81 году, который предназначался совсем для других технологий и в других рабочих условиях.
Может еще берестяную грамоту обсудим?
Может еще берестяную грамоту обсудим?
Я с удовольствием поговорю и о берестяных грамотах, но читатели могут не оценить такой темы на Хабре :)
ГОСТ может и не вчерашний, но действующий. Если вам доведется работать над серьезным проектом в государственной сфере или в другой ответственной сфере (энергетика, транспорт и так далее), от вас скорее всего потребут документацию, соответствующую именно ЕСПД (ГОСТ серии 19). Так что тема ничуть не устарела, хоть ГОСТ и не менялся 30 лет.
Не говоря уж о том, что ГОСТ позволяет очень гибко менять и структуру документов и их оформление в зависимости от задачи, решаемой в данный момент.
ГОСТ может и не вчерашний, но действующий. Если вам доведется работать над серьезным проектом в государственной сфере или в другой ответственной сфере (энергетика, транспорт и так далее), от вас скорее всего потребут документацию, соответствующую именно ЕСПД (ГОСТ серии 19). Так что тема ничуть не устарела, хоть ГОСТ и не менялся 30 лет.
Не говоря уж о том, что ГОСТ позволяет очень гибко менять и структуру документов и их оформление в зависимости от задачи, решаемой в данный момент.
Я не хочу обсуждать совсем другую сферу с другими уровнями риска и другими маштабами работы.
Речь о разработке игр. Здесь это не работает.
Речь о разработке игр. Здесь это не работает.
Получается еще более пестро. Я за минимизацию количества стилей в одном документе.
Согласен с Вами.
Моей целью было продемонстрировать стиль оформления ТЗ. Я посчитал что так будет гораздо полезнее для понимания смысла.
Моей целью было продемонстрировать стиль оформления ТЗ. Я посчитал что так будет гораздо полезнее для понимания смысла.
Это сео оптимизация текста :)
>Концепция («Про че игра?»)
Возможно стоит исправит на «Про что игра?»
Возможно стоит исправит на «Про что игра?»
«Поэтому так важно прилагать усилия к тому чтобы чтение документации было легким и приятным настолько, насколько это вообще возможно.»
Да, да и еще раз да! :)
Да, да и еще раз да! :)
Это все замечательно, если есть кому занимать и кто замотивирован это поддерживать :)
Но, с точки зрения обоснованности тратить время и ресурсы на документацию, планирование и архитектурная проработка должны уменьшать ошибки и проблемы во всем проекте. Но с этой точки зрения прототип конечного результата намного эффективнее.
В результате, на своих проектах, я создавал прототип ( корявый, все в заглушках, но функциональный ) без документации в команде из 2-3 человек, которые полностью владели всеми деталями проекта, и уже после того как по прототипу одобрялось все важное — писалась дока и так далее.
Но, с точки зрения обоснованности тратить время и ресурсы на документацию, планирование и архитектурная проработка должны уменьшать ошибки и проблемы во всем проекте. Но с этой точки зрения прототип конечного результата намного эффективнее.
В результате, на своих проектах, я создавал прототип ( корявый, все в заглушках, но функциональный ) без документации в команде из 2-3 человек, которые полностью владели всеми деталями проекта, и уже после того как по прототипу одобрялось все важное — писалась дока и так далее.
Твой случай как раз из «срезания углов»:
1) геймдизайнер вместо написания документации умеет программировать.
2) команда в 2-3 человека уже существует до запуска проекта в производство.
3) минимальный жизненный цикл (прототип) — экстремально простой и короткий.
В моем случае ни один из этих пунктов не выполнялся.
Поясни пожалуйста, что ты подразумеваешь под «одобрением всего важного»?
Лучше на конкретных примерах, если не сложно.
1) геймдизайнер вместо написания документации умеет программировать.
2) команда в 2-3 человека уже существует до запуска проекта в производство.
3) минимальный жизненный цикл (прототип) — экстремально простой и короткий.
В моем случае ни один из этих пунктов не выполнялся.
Поясни пожалуйста, что ты подразумеваешь под «одобрением всего важного»?
Лучше на конкретных примерах, если не сложно.
одобрением всего важного
уточнение важных деталей ТЗ у стекхолдеров
Именно ради таких как ты в требованиях к ТЗ я первым пунктом написал требование избегать искаженных английских терминов.
Руглиш — это плохо. :)
Руглиш — это плохо. :)
К сожалению, тезис
«Чем легче найти нужный пункт в документации и изменить его, не затрагивая остальное – тем лучше»
противоположен другому тезису:
«Многократные повторения. (Избегать ссылок по документу)».
Не раз сталкивался с тем, что при внесении очередного минорного изменения становится лень прочёсывать весь документ и копировать правки по всему тексту.
«Чем легче найти нужный пункт в документации и изменить его, не затрагивая остальное – тем лучше»
противоположен другому тезису:
«Многократные повторения. (Избегать ссылок по документу)».
Не раз сталкивался с тем, что при внесении очередного минорного изменения становится лень прочёсывать весь документ и копировать правки по всему тексту.
Попробуйте новую функцию в текстовых редакторах: поиск в тексте по ключевым словам. :)
Не смешно и не конструктивно. Если вы так делаете — значит, ваша документация плохо организована.
Вот способы сказать разными словами об одном и том же: «уникальное значение», «не должно повторяться», «используется как первичный ключ», «является потенциальным ключом», «встречается только один раз» и т. д. Перебирать в Ctrl+F все возможные синонимы ключевого слова — это крайне непродуктивно.
Вот способы сказать разными словами об одном и том же: «уникальное значение», «не должно повторяться», «используется как первичный ключ», «является потенциальным ключом», «встречается только один раз» и т. д. Перебирать в Ctrl+F все возможные синонимы ключевого слова — это крайне непродуктивно.
Вы правы. Проблема с обновлением есть.
А моя документация — это не сад камней, а скорее обломки дома после урагана. Слишком мало ресурсов на нее выделено (все-таки это стартап) и слишком быстро растет энтропия в процессе разработки.
Именно поэтому я и написал эту статью — как бороться с энтропией и что такое красивая документация.
На мой взгляд выход как раз тех правилах, которые я выработал по названиям объектов.
Уже на этапе планирования можно выработать стратегию имен сущностей, пока все имена находятся рядом в одном списке, а не разбросаны по разным документам.
Я специально подчеркнул, что одна и та-же сущность должна иметь постоянное название по русски и по английски. (очень часто путаница возникает при переводе)
Английские имена для кода, вообще не меняются и не склоняются — это одно из требований кода. По ним вполне удобно искать все упоминания в тексте.
А моя документация — это не сад камней, а скорее обломки дома после урагана. Слишком мало ресурсов на нее выделено (все-таки это стартап) и слишком быстро растет энтропия в процессе разработки.
Именно поэтому я и написал эту статью — как бороться с энтропией и что такое красивая документация.
На мой взгляд выход как раз тех правилах, которые я выработал по названиям объектов.
Уже на этапе планирования можно выработать стратегию имен сущностей, пока все имена находятся рядом в одном списке, а не разбросаны по разным документам.
Я специально подчеркнул, что одна и та-же сущность должна иметь постоянное название по русски и по английски. (очень часто путаница возникает при переводе)
Английские имена для кода, вообще не меняются и не склоняются — это одно из требований кода. По ним вполне удобно искать все упоминания в тексте.
Я тоже вот захотел спросить «Как Вам удаётся совмещать требования этих двух пунктов».
Вы хотите сказать, что каждый раз упоминая объект по русскому наименованию, вы рядом упоминаете его по английскому несклоняемому имени? И наверно держите в документе ещё и словарик / алфавитный указатель?
Если объект нагруженный, то его упоминания могут быть во множестве и в огромном количестве разных контекстов. Когда один из контекстов поменялся, прочёсывать все его упоминания даже с фиксированным именем может стать напряжным.
Вы хотите сказать, что каждый раз упоминая объект по русскому наименованию, вы рядом упоминаете его по английскому несклоняемому имени? И наверно держите в документе ещё и словарик / алфавитный указатель?
Если объект нагруженный, то его упоминания могут быть во множестве и в огромном количестве разных контекстов. Когда один из контекстов поменялся, прочёсывать все его упоминания даже с фиксированным именем может стать напряжным.
Нет, не хочу.
Просто Вы намеренно искажаете написанное в статье до абсурда.
Просто Вы намеренно искажаете написанное в статье до абсурда.
Если честно, даже не думал ни доводить до абсурда, ни даже наезжать на Вас. Просто имею аналогичные представления о качестве текста и соответственно аналогичную проблему. И пока её не решил для себя. Думал, мож Вы что-то придумали или узнали…
Когда становится понятно что объект достаточно нагруженный — ему выделяют оттдельный документ-файл. В этот файл дописываются все ссылки на другие документы-контексты.
Высокая нагруженность одного класса — это явный признак плохой декомпозиции и будущее проблемное место в коде. Обязательно ведутся дополнительные исследования предметной области, чтобы прояснить этот сложным момент.
Никаких особых словариков не ведется. В роли словариков выступают списки классов.
Актуальность связи между классами-документами не отслеживается. Вместо этого выработанные правила/требования применяются при случайной ревизии отдельного документа, чтобы оценить его полноту. Если указанны не все связи — документ определенно не полон.
Хорошая политика именований позволяет сделать навигацию между классами интуитивно понятной.
3 варианта названий одного класса как раз и помогают нащупывать правильную стратегию именований. Это бывает не просто.
Высокая нагруженность одного класса — это явный признак плохой декомпозиции и будущее проблемное место в коде. Обязательно ведутся дополнительные исследования предметной области, чтобы прояснить этот сложным момент.
Никаких особых словариков не ведется. В роли словариков выступают списки классов.
Актуальность связи между классами-документами не отслеживается. Вместо этого выработанные правила/требования применяются при случайной ревизии отдельного документа, чтобы оценить его полноту. Если указанны не все связи — документ определенно не полон.
Хорошая политика именований позволяет сделать навигацию между классами интуитивно понятной.
3 варианта названий одного класса как раз и помогают нащупывать правильную стратегию именований. Это бывает не просто.
Sign up to leave a comment.
Как создать ТЗ для программиста