Совместная работа

[antonzol]

Стала задача по разработке серьезной системы.

Перед началом работы хочется определится с техническими деталями.

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

Нужна система, которая поможет вести документацию по проекту (ТЗ, инструкции, главные идеи, чейнджлог, коментарии...)

Подскажите пожалуйста, какой системой для совместной работы вы пользуетесь?

С системой определились - SVN.

Теперь остался вопрос - что записывать в документацию.

Для предыдущих проектов документация велась следующим образом:

структура базы данных

список процедур и функций (что умеет делать сайт)

пользовательский интерфейс

Поделитесь пожалуйста структурой своей документации.

Цель - сделать проект максимально независимым от одного разработчика.

Edited June 6, 2011 by antonzol

[Vlad]

Я использовал эту

http://ru.wikipedia.org/wiki/Redmine

Она на Ruby правда, не всем подойдёт.

[sigma77]

antonzol,

Может это поможет определиться:

http://habrahabr.ru/blogs/pm/109075/

http://habrahabr.ru/blogs/pm/110643/

[antonzol]

Пример предыдущего ТЗ, которое в процессе доработки модифицировалось неоднократно и стало не красивым.

ТЗ

Хочется сейчас выработать "правильную" систему для ведения документации. Тут я имею в виду не инструмент, а сущность, что там писать.

Как писал в предыдущем посте : Цель - сделать проект максимально независимым от одного разработчика.

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

[arez]

Это ужасное ТЗ, причем само понятие ТЗ уже ужасно т.к. в основу у вас заложена логика которую нужно документировать, объяснять и что самое страшное изучать...используйте ORM, MVC, unit testing и прочие паттерны и методологии. Код не должен комментироваться и тем более документироваться. Если вы описываете пользовательский интерфейс то он обязательно должен содержать экраны (шаблоны) взаимодействия.

ЗЫ:

http://www.ozon.ru/context/detail/id/5508646/

http://www.ozon.ru/context/detail/id/4952415/

http://www.ozon.ru/context/detail/id/5011068/

[antonzol]

arez, оцените такую схему описания:

1. Концепция. Для чего вообще система.

2. Перечень терминов, сокращений.

3. Описываю БД.

4. Описываю процедуры (функции) для работы с БД.

5. Описываю системные функции: логика (физика, математика) системы.

6. Описываю интерфейс, логику работы с интерфейсом (как пользовательская часть(фронтенд) так и админка)

7. Описываю дополнительные фишки, например запреты, ограничения, лимиты, которых нету в коде непосредственно

8. Требования к софту на сервере.

[arez]

1-2 нужно

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

6-7 это нужно объединить в так называемые "пользовательские экраны" в которых видно то как пользователь работает с системой какие ошибки может совершать, какие исключения могут возникнуть в системе, какие функции может предоставить система и т.д. и т.п. Вообще любое проектирование (планирование и разработка) должны основываться на этих экранах, программисты, верстальщики, дизайнеры, тестировщики должны видеть перед глазами такие экраны что бы понимать что от них требуется.

8 - нужно объединить с пунктами 1-2

Года два назад при разработки проектов я тоже пытался вести обширную документацию, писал огромные ТЗ но все это приводило к одному и тому же - ТЗ устаревало как только проект начинали писать, документация по проекту ни кому особо не нужна, она поднималась лишь в том случаи когда возникали споры между заказчиком и исполнителем при этом суть спора в документации имела такую старую версию что одеяло могли тянуть на себя обе стороны. Сейчас дела обстоят гораздо проще, есть основной документ проекта в котором описываются в простой понятной форме зачем, для кого и как мы делаем проект. Этот документ не ТЗ он содержит в себе как основополагающие вещи - концепция, словарь терминов и т.д. так и вещи которые могут измениться в процессе разработки (например экономические потребности или технологические ресурсы). После первой версии такого документа проектировщик (или группа проектировщиков) определяет роли в системе и "рисует" экраны взаимодействия, после чего уточняется основной документ проекта и экраны отдаются дальше по цепочке разработки и так циклически до первой рабочей версии. Возможно не каждому проекту может подойти такая методология и конечно она требует применения инструментов и ресурсов более высокого уровня чем "сборщик на коленке", но в моем случаи она работает очень эффективно.

PS:

http://www.ozon.ru/context/detail/id/4710758/

http://www.ozon.ru/context/detail/id/83760/

[alanvanduke]

Я использовал эту

http://ru.wikipedia.org/wiki/Redmine

Она на Ruby правда, не всем подойдёт.

Работали с Рэдмайном - очень правильная системка. Я думаю, поднять ради проектов можно. На PHP толковых так и не смогли найти.