Всем привет! На работе возникла потребность вести техническую документацию по сделанным доработкам (описание добавленных объектов и функционала, зачем, для чего, как работает и тп.). Сейчас решаем, как это лучше делать. Ведете ли вы у себя на работе нечто подобное? В каком виде? Есть ли для этого какие-то специализированные решения (какое-то спец. ПО или вроде того)?

Никогда не вел, наверное зря,  потому что через месяц уже могу не вспомнить где что зачем делал

Ну, баг-трекер, юзер-стори. Сначала появляется тикет, по нему общение, планирование, разработка, тестирование. Накопленное общение, скриншоты - вот уже и сырая документация.

Asana, Jira

Вот

(3) Что вот?

(4) Каков вопрос, таков и ответ.

Краткое, смысловое описание нужно вести непосредственно в программных модулях.

(5) А какое ПО используете? Какое-то готовое решение? Или своей разработки?

(7) Хранилище, выгрузка в гит, сервер сборки и тестирования.

(6) Старо.
Если дорабатывается, например, тиражируемое решение, то, скажите на милость, Клиенту зачем знать когда и зачем вы это исправили?

ИМХО, в релизе должны быть только функциональные комменты, объяснения вне объявлений - хлам.

(9) Речь про техническую документацию, а не про руководство пользователя.

Я слышал есть решения, делающие выгрузку из хранилища с историей всех изменений объектов... Кто-то сталкивался с таким?

Я так понимаю, никакого специализированного решения для ведения тех. документации, по типу MSProject, например, не существует?

(11) такое решение можно сделать самому через команду пакетного запуска конфигуратора

(13) А можно поподробнее?

(9)А чем они там мешают?

(14)
/ConfigurationRepositoryReport <имя файла> [-NBegin <номер версии>] [-NEnd <номер версии>] [-GroupByObject] [-GroupByComment] — построение отчета по истории хранилища. Если параметры группировки не указаны и режим совместимости указан "Не используется", то отчет формируется с группировкой по версиям. В режимах совместимости "Версия 8.1" и "Версия 8.2.13" отчет формируется с группировкой по объектам. Если конфигурация базы данных отличается от редактируемой по свойству совместимости, при обработке командной строки учитывается значение режима совместимости конфигурации базы данных.

<имя файла> — имя файла, в который выводится отчет;
NBegin — номер сохраненной версии, от которой начинается строиться отчет;
NEnd — номер сохраненной версии, по которую строится отчет;
GroupByObject — признак формирования отчета по версиям с группировкой по объектам;
GroupByComment — признак формирования отчета по версиям с группировкой по комментарию.

Я видел на одном месте такое решение - добавили в конфигурацию общий модуль "Комментарии" и там просто текстом с оформлением описывали что добавили, зачем, почему и как работает. Такое никуда не пропадет :)

Как вы вообще считаете, нужна отдельная подробная документация, или достаточно просто подробных комментариев и продуманной архитектуры решения?

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

(18) если есть ресурсы или отдельные люди для этого, то почему бы и нет. Но надо понимать, что это тоже трудозатраты

(17) С таким же успехом можно просто макет использовать и писать туда, что да, как и почему.

(17) Видел такое в семерке.

(18) Если разрабатывается тиражируемое решение, без этого никак.

(22) Если разрабатывается тиражируемое решение, без этого никак.

Для типовых бы точно не помешало :)

(23) Так у них-то есть!

(24) Где? Руководство пользователя - есть. А где описание программной архитектуры, механизмов работы и тп.? Техническая часть.

Тупое пост-документирование это скучное дело.
Лучше разрабатывать через описание функционала и проходимых тестов (не автоматизированных тоже катит) - помогает не упустить ничего в сложных системах и документация остается.

https://hkar.ru/Po2e

(26) Лучше разрабатывать через описание функционала и проходимых тестов

Т. е. сначала подробно описали функционал, потом сделали по описанию, а оно осталось как документация, так?

(27) Да.
Только этот процесс постоянный - описал-> напилил что описал-> по ходу дела напилил ещё сверху -> описал что сделал.

История показала, что чисто в одну сторону (от документации к разработке или, наоборот, от разработки к документации) никогда не бывает.

(25) Плюсую. Только у БСП хоть какая-то тех. документация есть.

(25) (29) Есть — у них, то есть у желто-красных. Нам, простым смертным, недоступно.

(30) У кого-то есть лярд мильёнов баксов. Мне от этого не теплее ни разу )

(0) канонический рецепт: нужна система учета задач + в коде в обязательном порядке комментарии с номером задачи, по которой это сделано.

Система учета - любая. Пофиг абсолютно - они на вкус и цвет все разные, каждому нравится что-то свое.
Как оформлять комментарии - тоже дело вкуса.
Главное - чтобы и то, и другое было.

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

Если нужно вставить более 2-3 строк, то пишу функцию в отдельном общем модуле доработок. Свою вставку, если 2 строки и более помечаю:
//+Метка Дата
//-Метка
В общем модуле доработок ниже отдельно:
// Дата Описание что, зачем, для чего...

(33) Ну да, представь что некий алхимик научился на глазок путем практики готовить любое зелье.

А тут приходят какие то умники с теорией химии и теперь требуют все процессы описывать сначала формулами...

(35) херня это все на палке. Цель разработки в том, чтобы релизы релизить с новыми фичами, потребными потребителям. А все эти процессы-шмацессы - это всё профанация и культ карго.

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

А зачем? Обычно внятного комментария в коде достаточно, а полный список изменений всегда виден при сравнении доработанной конфы с типовой...

Конфигурация на 1С по учету задач + комментарии в коде с номером (кодом) задачи + внятные имена переменных и методов + активное использование свойств "Комментарий" и "Подсказка" в дереве метаданных / на формах

в тестовом файле специального формата типа CSV

(40)Удобно?

(36) Вот эта гонка за новыми фичами и выходит в результате багнутыми релизами.

И фиг то с багами, но когда одно и тоже делают в одной конфе по разному!

Банальный пример в ERP2 импорт/экспорт Эксель для разных документов, тут так, а вот в соседнем документе мы ля изобрели новую ХЕ.
Тут нуна выбрать файлик, а тут сначала откройте эксель и сделайте копи/пасте в 1С... Слов нет...

да, ведем, через Тестер, кроме самого сценария, кратко описываем функционал в тексте, конфу поищите на гитхабе

Метки при помещение в хранилище. + краткий комментарий в коде.

(42) а меж тем ЕРП-то делается как раз через этот навозный документ-дривен девеломпент - сначала модель в СППР, потом код. И накуя, спрашивается, оно рабочему человеку надо?

Теперь представим что куча кусков кода фвнкций и процедур разбросана по куче модулей. И даже все за комментировано но в итоге НФИГА ЭТО ВСЕ - непонятно...

Иногда когда перфекционизм зашкаливает овер 282% - в общем описании конфигурации пишу типа
Сделано то то и тото с целью того т и тогото или а чем смысл доработок ; то есть по сути нааратчацшее описание задачт

//Кухарь 02.11.16 начало
//Будем РеквизитыСправочников грузить так же
//ИначеЕсли ВидОбъекта="ИнформацияШКЛН" тогда    
ИначеЕсли ВидОбъекта="ИнформацияШКЛН" или ВидОбъекта="РеквизитыСправочников" тогда    
//Кухарь 02.11.16 конец

Ведем на wiki движке

(45) хочу выразить глубочайшую признательность за разъяснение сложной предметной области понятными словами. Миста - лучший учитель.

(45) Иначе вышло бы не ЕРП, а сплошной навоз.

(51) нет. От навоза ЕРП удерживает не СППР, а ниличие одного строго определенного заказчика.
Когда у одной системы 100500 разных заказчиков которые тянут одело на себя, тогда хоть заэспэпээрься в кровь - получится навоз.
По опыту знаю.

Никто не мешает писать комментарии в модуле, делать справку в объектах и вести отдельный файл с описанием алгоритмов и способов реализации.

(53) Лень мешает, и то что никому это практически не нужно

Пока не будет выделенного приемщика комиттов, вероятность того что не взлетит ~95%

(49) А чем это в принципе отличается от ведения в простом word/excel-файле или макете конфигурации?

(56) Совместная работа, доступ в любое врем

По сути только в 26 ведут.
Те кто говорят про багтрекеры и комментарии в коде, просто не сталкивались с разработкой решения, группой программистов, которое используется несколькими компаниями.

Там начинаются мансы типа :
- процедура расчеты скидки написана два раза разными людьми, в разных модулях. Под эти процедуры добавлены два разных по форме, одинаковых по сути справочника со шкалой наценок.
- программист переходит с разработки одной подсистемы на другую. недавно разработанную. Там 10 документов, 20 справочников, два десятка разных регистров, куча процедур в общих модулях. Несколько сотен закрытых заявок в трекере, типа "добавить галочку", "исправить ошибку". Нужно в это всё въехать.
- другой программист начинает другую подсистему. Где 10 справочников можно использовать из предыдущей, слегка расширив и модифицировав. Но он с предыдущей незнаком.

В моем опыте это было реализовано через пару архитекторов, которые на любое более-менее значимое изменение писали ТЗ программистам. Они держали в памяти назначения всех регистров и документов. Но это сильно нестабильно, так как заменить их нельзя и они часто бывают узким местом в процессе разработки.

(58) Для кого то очень сложно понять что в "10 документов, 20 справочников, два десятка разных регистров, куча процедур в общих модулях" въехать сложнее чем за несколько часов.

И если программист не может разобраться в конфе и/или воспользоваться поиском по ней перед тем как "писать код ..ять", то ему явно переплачивают.

Ведём на MediaWiki

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

А СППР никто для этого не использовал?

(59) но если в коде поработали "элитные" программисты, особенно по очереди несколько разных, превратив код во взрыв на макаронной фабрике - то тупить будет хоть какой спец.

Еще документ документу рознь.

(57) К опубликованному документу не сложно организовать совместный доступ и совместно его редактировать.

(59) Мне кажется ты в группе не работал никогда.

(58) Выделенный архитектор - это единственно возможное решение ситуации

(62) я использовал. Для коробочного решения он дает какие-то преимущества. Для кастомной разработки, у которой нет конца и четкой цели - куита это всё.

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

А все потому что х..к, х..к и в продакшн

Для коробки, у которой один продакт-менеджер и четкие границы области назначения СППР - самое оно. Как, в прочем, и любая другая система для документации требований.

(69) именно!
Более эффективного способа сделать что-то новое просто не существует. Это следствие особенностей устройства человеческих мозгов и сущности творческого процесса. Творчество - это только и именно пробы и ошибки. То есть творчество - это ХХП.

При этом, документирование, конечно же, важно. Но нельзя телегу в него запрягать.

(71) скорее, более неэффективного
когда придется на опытной разгребать

(73) это теория. На практике вся эта документация летит псу под хвост обычно и приходится передокументировывать.
Особенно, если между [требования задокументированы] и [требования разработаны] проходит пара месяцев.
Потому, что требования-то зафиксированы, а бизнес-то живет и меняется каждый день по чуть-чуть.

(74) творчество это круто, но даже Достоевский говорил, что рамки и дисциплина только помогает творчеству
что уж говорить про инжиниринг
ххп - это круто, когда ты не участвуешь во внедрении, а только "творишь"

Что такое ХХП?

(76) Хренак, хренак и в продакшен :)

(76) Метод разработки ПО. Популярный.

(75) Особенно на этапе внедрения. Нужно ошибки срочно исправлять.
А документацию исправлять некому

(79) на этапе внедреные ты разгребаешь последствия ххп, а не "особенно на этапе внедрения"

Ясно. Спасибо.

Прикольный схематоз.

(75) угу, только достоевский ни одного приложения до продакшна не дотащил.

(80) не бывает идеального софта, который разрабатывали-разрабатывали, а потом оно - хренак - и само деплойнулось на продакте без напилинга. В реальном мире не бывает. В стране волшебных коббитов и дивных всяких итильфов - может быть. Но - не в реальном мире.

(83) не бывает, только не нужно говорить мол, ххп - это и есть путь

(83) таки достоевский творил в рамках: с бюджетом и сроками

(85) это не сравнимые вещи
(48) я говорю, что документирование - это тоже не есть путь. Путь - где-то по середине.

(86) сравнимые - я парировал тебе, что творчество должно быть в разумном коридоре

СППР (ошибки+техпроекты) + git (история изменений)

(87) нет, нет и еще раз нет. Творчество ни кому ни чего не должно. То, что подходило Достоевскому, подходило только ему. Если взять какого-нибудь Пушкина и навязать ему процессы Достоевского, то получится бесплодный и несчастный Пушкин. Сравнивая процесс разработки ПО (обобщенный и сферический в вакууме) с конкретным процессом творческой деятельности конкретного Достоевского, ты подменяешь понятия и манипулируешь фактами. Добродетельные люди так не поступают. Одумайся.

(0) Активно веду в Google Docs

(0) Гитлаб: тикеты, ветки, теги с релизами и скрины для пользователей в описании.

>но даже Достоевский говорил, что рамки и дисциплина только помогает творчеству

только книжки он писал почему то под мотивацией очередного проигрыша в рулетку

Программирование не совсем творчество. Скорее творческое ремесло

(65) Кроссплатформенность

(0) Redmine.
В метаданные (реквизиты, объекты...) и в доработки кода вписываю ссылку на странички редмайна. :-)

(66) Работал, только не рядовым кодером.
Так то все бардаки в архитектуре/коде только от бардака и лени в головах, и совершенно неважно что использовать (точнее не использовать) для техдокументации/багтрекинга.
Если сотрудники не хотят (плохо промотивированы) - они что угодно запорют.

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

(100) это СППР

(97) Что мешает использовать google docs или office 360?

(102) Совместное редактирование можно и в обычном екселе

(102) Так оно в интранете не заработает, наверное

(104) Все заработает.

(102) Office 365 Personal -  $69.99 per year
нахер надо...

(106) Есть бесплатный сервис, если регистрируешь почту на outlook.com.

(107) ссыль?

попробовал бесплатную версию на месяц получить потребовали заполнить платежные реквизиты. типа: "после окончания бесплатного месяца мы будим снимать с вас 399 руб пер монс".
да пошли они при наличии гугледока.

(108)

http://www.outlook.com
http://www.hotmail.com

После регистрации Список служб и Microsoft Excel. У меня все работает.

ага, получилось.