Как лучше документировать разработку программы.

Вопросы программирования и использования среды Lazarus.

Модератор: Модераторы

Как лучше документировать разработку программы.

Сообщение bpg » 02.05.2018 14:01:24

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

Сначала установил на свой хостинг mantis , но блин получилось что разобраться и настроить и потом работать с ним почти столько же времени займет, ка и написание программы.
Мне не нужна коллективная разработка, пишу сам и для своих нужд (своего предприятия). Так же похе...сь идея со своим локальным svn сервером, еще трудозатратнее оказалось

Что посоветуете?

P.S. Думал в настройках программы на вкладке настроек сделать StringGrid и туда при каждой компиляции записывать дату время сборки и версию. Как считаете это нормально?
bpg
новенький
 
Сообщения: 36
Зарегистрирован: 28.11.2017 21:23:18

Re: Как лучше документировать разработку программы.

Сообщение Pavia » 02.05.2018 17:24:36

Пусть об этом болит голова у начальников и у менеджеров.
А почему git не использовать? И чем вам svn оказался трудозатратен?
Вы же когда комите должны отдавать только проверенные файлы. Файл должен компилироваться, быть проверен и в описание вы указываете либо какие ошибки закрыли либо какую фичу добавили. Каждое действие не надо описывать.

У моих коллег вообще версия выходит раз 1 год и до 4 промежуточных.

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

Судя по другим наши вообще не заботятся. О документировании.

bpg писал(а):для своих нужд (своего предприятия).

Это не важно у вас должно быть основание на разработку. А то так придут и спросят ты чем занимаешься кто поручил и так далее? Почему ящике не разгружаешь, а пишешь какие-то программы?
Основанием является ТЗ. Как по мне лучшей шаблон для ТЗ это SRS.

Так же пишется ряд документов: руководство пользователя, руководство для администратора по установке, руководство для программиста где описывается архитектура и так далее.

Руководство пользователя описано в DOC файле.
Справки по функциям нет. И писать не собираюсь ибо менеджеры не требуют. Если бы требовали писал в DOC.
На самом деле уже пора описывать.

Руководство администратора у меня размазано по нескольким документам. Формальный что-бы проверяющие от: DOC-файлов.
Плюс скрипт установки который делает всё за админа снабжён комментариями к каждой строчке.

//[!] разбросаны по тексту. Это известные ошибки которые надо пофиксить. Пишу так что-бы было понятно в чём ошибка любому даже со стороны.
Вернее пишу коротко, а потом при ревью дописываю развернутый ответ.
Todo лучше собирать в отельный файл и крепить к проекту.
Так же виду еженедельные планы - в Notepad++. Вот здесь перечисляю всё что надо доделать либо протестировать либо переписать.
Периодически делаю рефакторинг кода.

Найденные ошибки заношу в еженедельный план. На самом деле код у меня ещё тестируют "специально обученные" люди. Они найденные ошибки заносят в DOC файл. И судя по всему ещё и в JIRA но меня это не касается.
Помимо прочего есть ещё файл проблема-решение где описываю какие проблемы в ходе разработки встретил и и какие решения нашёл принял - это что-то типо блога.

Так как никто в этом не разбирается. То с меня ничего не требуют над душой не стоят. Из того что требовали это РЭ оператора и РЭ администратора - что-бы было. Как думал то и записал.
Поэтому всю документацию веду для себя в том виде в котором считаю нужным. А я в этом вопросе строгости не придерживаюсь.
Аватара пользователя
Pavia
постоялец
 
Сообщения: 290
Зарегистрирован: 07.01.2011 12:46:51

Re: Как лучше документировать разработку программы.

Сообщение скалогрыз » 02.05.2018 18:44:02

первый пост стоит из солянки проблем. (но солянки хорошей, потому что эти проблемы нужно решать в любом проекте)

1) документация (кода, руководство пользователя, руководство администратора) - советую поставить Вики. Например, MediaWiki, но пойдёт любая с веб доступом. Почему. Потому что - всегда доступна всем одновременно. Все всегда видят самую актуальную версию (в отличии от обмена .doc файлами). Всегда все видят историю изменений. Для использования нужен долько браузер. При желании можно переложить в документ (если нужно передать конечному пользователю или дамину).

2) релизы - нужно уметь в бранчи (svn или git - не важно, но нужно уметь)

3) контроль версий. Чё-то я не уверен что SVN сервер настолько сложен в настройке. Если есть сервак под виндой, то я советую VisualSVN server. Всё настраивается в окошечках.

4) mantis хорошо. Лучше потратить время и настроить его.
скалогрыз
долгожитель
 
Сообщения: 1803
Зарегистрирован: 03.09.2008 02:36:48

Re: Как лучше документировать разработку программы.

Сообщение Mirage » 02.05.2018 19:49:26

Что изменилось в программе и почему, пишется в т.н. коммит сообщениях системы контроля версий. С ее же помощью можно организовывать релизы, хотфиксы и разрабатывать крупные фичи/рефакторинги без особых трудностей. Не использование СКВ в 2018 году не имеет оправданий.
Нормальная система контроля версий не требует никакого сервера. Например - git, mercurial. SVN давно умер.
Документировать код и API удобно в комментариях. В случае API это описание класса или метода в комментарии непосредственно над ним. Есть тулзы, которые позволяют собрать из таких комментариев красивый документ в любом нравящемся менеджеру формате - doc, pdf, html.
К сожалению, разработчики FPC так не делают, поэтому за документацией надо куда-то лазить каждый раз.
Еще есть системы управления багами/задачами типа той же джиры. В т.ч. онлайн и бесплатные для некоммерческих продуктов. Хорошие примеры - Youtrack, taiga.io. Mantis тоже смахивает на зомби.
Хотя если в одного разрабатывать, то это лишнее. Я обхожусь текстовым файликом для баклога, где записываю что надо бы сделать и что буду делать конкретно сейчас. Сделав, удаляю. Но он все равно растет как на дрожжах. :(
Mirage
энтузиаст
 
Сообщения: 881
Зарегистрирован: 06.05.2005 20:29:07
Откуда: Russia

Re: Как лучше документировать разработку программы.

Сообщение mirk » 02.05.2018 23:02:45

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

Лучше уж тектовый файлик.
Вордовский файлик не очень хорошо ложится в системы контроля версий, да и его дольше открывать.

bpg писал(а):Что посоветуете?

Нанять системного администратора ;)
Далеко не все программисты умеют быть админами, да и не так часто требуется это. Если не удалось сходу разобраться с mantis и svn - админство видать совсем "не ваше".

скалогрыз писал(а):1) документация (кода, руководство пользователя, руководство администратора) - советую поставить Вики.

+1
Стоит добавить, что есть модели генерации pdf из статей wiki. Да и не очень прям сложно реализовать свой если стандартный не подходит по каким-нить причинам.

скалогрыз писал(а):Чё-то я не уверен что SVN сервер настолько сложен в настройке.

+100500 :roll:

скалогрыз писал(а):4) mantis хорошо. Лучше потратить время и настроить его.

mantis наверное один из самый простых вариантов по установке.
Можно еще посмотреть в сторону trac.

Mirage писал(а):Нормальная система контроля версий не требует никакого сервера. Например - git, mercurial. SVN давно умер.

Не стоит принимать рекламные бредни менеджеров за реальное положение дел :lol:
Вы считаете что установив себе серверную часть git вы избавились от сервера? Нет, вы просто переместили сервер к себе на компьютер. Если вам не нужен сервер, так что вам мешает установить SNV на себе на компьютер?

Mirage писал(а):Mantis тоже смахивает на зомби.

Чем конкретно? Какими параметрами вы руководствуетесь?

Mirage писал(а):Хотя если в одного разрабатывать, то это лишнее. Я обхожусь текстовым файликом для баклога, где записываю что надо бы сделать и что буду делать конкретно сейчас. Сделав, удаляю.

Это очень плохое решение. Даже для собственной организации очень удобно пользоваться всеми плюсами от систем управления разработкой.
mirk
постоялец
 
Сообщения: 317
Зарегистрирован: 24.09.2007 10:03:39

Re: Как лучше документировать разработку программы.

Сообщение stanilar » 03.05.2018 00:28:13

bpg писал(а):еще трудозатратнее оказалось


Вы просто не привыкли к git/svn. Если бы привыкли - таких вопросов не было бы. Советую просто понабивать руку с git на кошках. Когда привыкните даже не будете понимать как без этого раньше жили.

Особо удобно смотреть в git/svn какая строчка по какой задаче менялась.
stanilar
постоялец
 
Сообщения: 289
Зарегистрирован: 09.03.2010 19:09:02

Re: Как лучше документировать разработку программы.

Сообщение Mirage » 03.05.2018 01:59:29

mirk писал(а):Вы считаете что установив себе серверную часть git вы избавились от сервера? Если вам не нужен сервер, так что вам мешает установить SNV на себе на компьютер?


Речь ведь о разработке одним человеком. Зачем сервер?

mirk писал(а):Чем конкретно? Какими параметрами вы руководствуетесь?


Да чисто видом UI и строчкой "© 2000 - 2012" внизу на bugs.freepascal.org.

mirk писал(а):Это очень плохое решение. Даже для собственной организации очень удобно пользоваться всеми плюсами от систем управления разработкой.


Не скажу что хорошее, но с системами было хуже, т.к. так просто пришедшую в голову мысль или замеченный баг в веб интерфейсе не впишешь.
Может, если будет быстрый и удобный десктопный клиент для этого дела, тогда да... Но его ведь не будет.
А какими плюсами пользуетесь Вы?
Mirage
энтузиаст
 
Сообщения: 881
Зарегистрирован: 06.05.2005 20:29:07
Откуда: Russia

Re: Как лучше документировать разработку программы.

Сообщение скалогрыз » 03.05.2018 06:59:45

Mirage писал(а):Речь ведь о разработке одним человеком. Зачем сервер?

ну если одним, так и svn-у сервак не нужен. Создать папку-репозиторий, и работать с ней.
(тогда и вики не нужна. тупо - текстовый файл)

Но вот все мои личные проекты - есть и отдельный сервак, и отдельная вики, и отдельный мантис.
Просто потому что это удобно, т.к. 1) иногда приходится перемещатся физически (на работу!). 2) голова не болит насчёт трескающихся винтов. 3) облегчает бекап. 4) могу всё что захочу делать со своим компом и не боятся повредить рабочую инфраструктуру;
Всё это живёт на VDS серваке, и стоит около 800р в месяц. Слава Богу, могу себе такую роскошь позволить.

Mirage писал(а):Да чисто видом UI и строчкой "© 2000 - 2012" внизу на bugs.freepascal.org.

а это показатель, что программисты <> админы.
Админа хлебом не корми, дай поставить новую версию (как минимум - "безопасности ради"). Программист будет сидеть на том, к чему привык до последнего. :D

вот тут демка мантиса. Интерфейс (давно уже) переделан на bootstrap. Имхо, на мобилках теперь смотрится даже лучше, чем на десктопе.
и внизу красуется "Copyright © 2000 - 2018 MantisBT Team"
Если сравнивать Манист с Github Issues-трэкером, так на github-е это просто детский лепет.
Жиру я до конца не изучал, но тот функционал с которым удалось поработать - так Мантис тоже самое.

ЗЫ: как оказалось, что связка git/svn на GitHub-е, не позволяет использовать "svn blame". Посмотрев в "git blame" я расстроился - как можно было ожидать для каждой строчки пишется хеш. А я привык к номеру ревизии, который указывает хронологию изменения строк. Т.к. я сумел настроить себе вики+свн+мантис, то сильно задумался - а не написать ли мне убийцу ГитХаба :mrgreen:
скалогрыз
долгожитель
 
Сообщения: 1803
Зарегистрирован: 03.09.2008 02:36:48

Re: Как лучше документировать разработку программы.

Сообщение Vadim » 03.05.2018 10:59:21

У нас на работе пока не было такой командной разработки, чтобы требовался менеджмент. В основном каждый сам за себя, один Бог за всех... :-)
Несколько раз пробовали вести менеджмент работы отдела, но для этого требуется координатор, для которого эта задача была бы главная, а такого выделить было никак нельзя. Нач. отдела вообще весь увяз во взаимоотношениях с партнёрами и открещивается от менеджмента как может. Хотя, по идее, это как раз его работа. :-) В общем все прошлые разы ничего для коллективной работы у нас не прижилось. Сейчас в очередной раз пытаемся пользоваться одной из бесплатных программ (не скажу какой, дабы не было нечаянной рекламы... :-) ) посмотрим, что выйдет.
наши разработчики пользуются обычными текстовыми файлами. В конце разработки составляется пользовательский документ и проводится обучение пользователей. По поводу полноценной документации - не хватает человека, который бы её правильно делал. Программист, действительно, редко способен написать понятную всем документацию. Ему же самому всё понятно, не так ли? :-D Проблема осложняется ещё и тем, что по программированию у нас две параллельные ветки работы:
1) Основная, которая была изначально. Главная программа учёта наших фондов, под который создавался целый отдел программирования. Они этим и занимаются. От них никакой документации, окромя руководства пользователя, никогда добиться не удавалось. Условно говоря, если вдруг все разом программисты уволятся, никто это дело продолжить не сможет.
2) Не основная, но тем не менее сейчас не менее важная. Программы, которые работают с внешними, так сказать, пользователями, которые не являются сотрудниками учреждения. Этим занимается, вы не поверите, отдел администрирования комптехники. :-) Естественно не прерывая основной работы... ;-) Вот там то порядка с документацией больше. Я, к примеру, могу взять любой проект и буду его спокойно доделывать, потому что есть текстовые файлы о процессе разработки. Плюс к этому - комментарии в коде, чего в отделе программирования нет вообще. ;-)
Vadim
долгожитель
 
Сообщения: 4112
Зарегистрирован: 05.10.2006 08:52:59
Откуда: Красноярск

Re: Как лучше документировать разработку программы.

Сообщение serbod » 03.05.2018 12:49:39

Wiki - обязательно, самая простая и удобная система для документирования. Я пользуюсь DocuWiki

SVN или GIT - очень желательно, позволяет вести и просматривать историю изменений в коде. Для собственных нужд удобно VisualSVN server + TortoiseSVN, минимум настроек.

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

Трекер (Mantis или подобное) - нужен при групповой разработке. А если разработчик один, то гораздо проще и удобнее записывать задачи ручкой на бумаге, чтобы она всегда была на столе перед глазами. А по завершению задачи с удовольствием эту бумажку скомкать и выбросить.

Настроить сервер разработчика очень просто - нужен любой WAMP или LAMP, и в него установить wiki/svn/mantis по инструкции.
Аватара пользователя
serbod
постоялец
 
Сообщения: 449
Зарегистрирован: 16.09.2016 11:03:02
Откуда: Минск

Re: Как лучше документировать разработку программы.

Сообщение mirk » 03.05.2018 21:58:00

Mirage писал(а):Речь ведь о разработке одним человеком. Зачем сервер?

Потому что он требуется для работы конкретной программы. Если не называть эту часть сервером, она не перестанет быть им. Ну а вообще надо знать архитектуру разворачиваемого ПО, тогда и возникающие проблемы легче решаются.

Mirage писал(а):Да чисто видом UI и строчкой "© 2000 - 2012" внизу на bugs.freepascal.org.

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

Mirage писал(а):Не скажу что хорошее, но с системами было хуже, т.к. так просто пришедшую в голову мысль или замеченный баг в веб интерфейсе не впишешь.
Может, если будет быстрый и удобный десктопный клиент для этого дела, тогда да...

Какая разница между десктопным клиентом и веб решением?
Без проблем вся информация вносится и если надо прикрепляются дополнительные файлы.

Mirage писал(а):А какими плюсами пользуетесь Вы?

Учет багов, поиск в старых багах и во внесенных изменениях.
Учет планируемых новшеств.
Планирование релизов.
Написание документации и использование вики как блокнота.
Подключение с системе через интеренет из любой точки.

скалогрыз писал(а):Если сравнивать Манист с Github Issues-трэкером, так на github-е это просто детский лепет.

С trac работал? Как по сравнению с ним?

serbod писал(а):Я пользуюсь DocuWiki

Упарился с ее багами и ограничениями, надумал мигрировать на MediaWiki.

serbod писал(а):Трекер (Mantis или подобное) - нужен при групповой разработке. А если разработчик один, то гораздо проще и удобнее записывать задачи ручкой на бумаге, чтобы она всегда была на столе перед глазами. А по завершению задачи с удовольствием эту бумажку скомкать и выбросить.

Нет, нет и еще раз нет :)
Дяже одному разработчику очень полезен трекер. Баги нельзя править и забывать. Нужна история, ссылка на исправлени и т.п. Ведь баг можно позже проявиться немного в другом ключе или внесенные изменения повлияют на другой модуль и при исправлении опять появится старый баг.
Да и хотя бы не жалко своего времени на постоянные записи, поиски в открытых багах? Ведь проще клиентам дать возможность репортить баги и уже в системе назначать приоритеты и т.п. 21 век на дворе :)
mirk
постоялец
 
Сообщения: 317
Зарегистрирован: 24.09.2007 10:03:39

Re: Как лучше документировать разработку программы.

Сообщение serbod » 03.05.2018 23:54:19

Дяже одному разработчику очень полезен трекер. Баги нельзя править и забывать. Нужна история, ссылка на исправлени и т.п. Ведь баг можно позже проявиться немного в другом ключе или внесенные изменения повлияют на другой модуль и при исправлении опять появится старый баг.


Для предотвращения регрессии нужно чаще коммитить в SVN и подробнее писать в комментах, почему так сделано и на что это может повлиять. А то, что в трекере этот баг подробно описан, никак не защитит от повторения ошибки. Кто познал дзен - тот помечает грабли флажками.

Если просто нравится заниматься электронной бюрократией, то есть системы поинтереснее, чем Mantis - YouTrack или Redmine например. Там по любому поводу столько всякой красивой активности можно вести..
Аватара пользователя
serbod
постоялец
 
Сообщения: 449
Зарегистрирован: 16.09.2016 11:03:02
Откуда: Минск

Re: Как лучше документировать разработку программы.

Сообщение Mirage » 04.05.2018 04:00:24

скалогрыз писал(а):ну если одним, так и svn-у сервак не нужен. Создать папку-репозиторий, и работать с ней.(тогда и вики не нужна. тупо - текстовый файл)


А кто говорил, что нужен? Не нужен и хорошо. :)
Кстати, как там нынче с коммитами? Раньше сразу на сервер уходили, а если без сервера, то куда? Или прав mirk и сервер таки присутствует в любом случае?
А на внешнем серваке разместить инфраструктуру всегда хорошо и полезно, да.

скалогрыз писал(а):Если сравнивать Манист с Github Issues-трэкером, так на github-е это просто детский лепет.


Ну, Гитхаб не претендует тут ни на что. Там трекер чисто "чтобы было" сделан.
А вот в сравнении с серьезными решениями демка как-то не впечатляет. Не увидел канбан доски, возможности написать (не накликать) и сохранить свой фильтр, да даже банальной диаграммы Ганта. А как насчет интеграции с Slack/Telegram?
А вот без бутстрапа жить можно. :)

mirk писал(а):Потому что он требуется для работы конкретной программы.


Тут рядом говорят, что можно и без. А если про git, то мне непонятно что именно Вы утверждаете? Что программа git является сервером?

mirk писал(а):Какая разница между десктопным клиентом и веб решением?Без проблем вся информация вносится и если надо прикрепляются дополнительные файлы.


Разница в скорости, если, конечно, десктопное решение продумано и не лезет каждый раз в сеть, когда пользователю что-то нужно сделать.
А писать приходящие мысли в веб решение это нонсенс.
Они убегут, я даже залогиниться не успею. :)

mirk писал(а):Учет багов, поиск в старых багах и во внесенных изменениях.Учет планируемых новшеств.Планирование релизов.Написание документации и использование вики как блокнота.Подключение с системе через интеренет из любой точки.


Как раз это все успешно делаю в текстовом файлике. Где плюсы-то?
Кроме документации конечно. Кто вообще придумал вики пихать в трекер? Отдельные же продукты.
Mirage
энтузиаст
 
Сообщения: 881
Зарегистрирован: 06.05.2005 20:29:07
Откуда: Russia

Re: Как лучше документировать разработку программы.

Сообщение скалогрыз » 04.05.2018 07:34:00

Mirage писал(а):Кстати, как там нынче с коммитами? Раньше сразу на сервер уходили, а если без сервера, то куда?

в локальную репозиторию.
Mirage писал(а):Не увидел канбан доски возможности написать (не накликать) и сохранить свой фильтр, да даже банальной диаграммы Ганта. А как насчет интеграции с Slack/Telegram?
А вот без бутстрапа жить можно.

а я скажу - "так в мантисе же есть API, для плагинов", а ты скажешь "и чё, мне плагины теперь к нему писать что ли"?
тогда мне придёться ответить - "гуглите и обрящите":
Gantt
Slack
Kanban (имхо, канбан хорош для менеджеров, но не для исполнителей)
Telegram (недоплагин, т.к. требует вносить изменения в файлы, вместо "добавления плагина". Но идею передаёт :D. Переписать его в полноценный плагин вопрос 2х вечеров. Вообще в Мантисе встроенная RSS рассылка, но ей никто не пользуется(?!))
хотя, я думаю, тебя это не впечатлит ;)

Mirage писал(а):возможности написать (не накликать) и сохранить свой фильтр

ну "написать фильтр" такого плагина ещё не состряпали. :mrgreen:
а вот сохранять фильтры (накликивать свои и снова сохранять), так это древний функционал. Его можно увидеть ещё в FPC мантисе.

Mirage писал(а):А вот без бутстрапа жить можно

не соглашусь. Открой старый fpc мантис на мобилке.

mirk писал(а):С trac работал? Как по сравнению с ним?

не работал. Видел пару раз, но он мне показался слишком трудным в восприятии.


ууу, кстати, сайт интересный
скалогрыз
долгожитель
 
Сообщения: 1803
Зарегистрирован: 03.09.2008 02:36:48

Re: Как лучше документировать разработку программы.

Сообщение serbod » 04.05.2018 13:58:47

скалогрыз писал(а):имхо, канбан хорош для менеджеров, но не для исполнителей

Канбан - это методика визуализации задач, чтобы сделать их более "осязаемыми". Когда задачи висят где-то в трекере, то нет ощутимой разницы, сколько там в трекере задач висит - 1, 10 или 100.

А когда каждая задача занимает место на столе и постоянно мозолит глаза, то во-первых, не получится безгранично навешивать задачи, места на столе не хватит. Во-вторых, за новую задачу можно взяться только после выполнения уже взятой. В целом это естественно и непринужденно повышает дисциплину, распределяет нагрузку и повышает эффективность работы в целом.
Аватара пользователя
serbod
постоялец
 
Сообщения: 449
Зарегистрирован: 16.09.2016 11:03:02
Откуда: Минск

След.

Вернуться в Lazarus

Кто сейчас на конференции

Сейчас этот форум просматривают: нет зарегистрированных пользователей и гости: 26

Рейтинг@Mail.ru