ФлеймФорумПрограммирование

RTFM / WTFM (4 стр)

Страницы: 1 2 3 4
#45
16:39, 16 мая 2019

Мизраэль
> Примеры использования кода можно либо непосредственно в комментариях в коде
> писать, но я предпочитаю это отдельно делать. Если использовать тот же DocFX,
> то получается так, что у тебя в солюшене помимо проекта продукта, есть ещё
> проект документации
кроме примеров, к проектам идут тестовые приложения, и утилиты.
(наличие "тестов" зависит от проекта. Обычно тесты нужны для библиотек и движков)
Так что сам факт, того, что проект, это больше конечный продукт, а продукт + сопровождение к нему не должен никого пугать.

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

Но в наш гипертектсовый век, он-лайн документация это частенько вики. И правки отдельных страниц видны в истории.
А непосредственные релизные версии не фиксируются.

Мизраэль
> Получается, что и разработчики и документаторы работают с одним проектом, также
> через git тянут обновления и пушат изменения. Но мы до такого не доросли, если
> честно
не доросли в каком плане?
моральном (трудно обучить документаторов/банальная лень/другие приоритеты)
или
организационном (нет людей, чтобы за всем этим следить или даже организовать)

Мизраэль
> У нас по завершении каждой фичи разработчики должны сделать детальное описание на вики как это работает, описание классов и т.п. по максимуму.
> Потом на основании этой информации а) документаторы напишут документацию,
Организационный момент:
Когда описывается функционал в вики, должны ли разработчики придерживаться каких-то стандартов. Или просто описывают, как могут.
и при разборе таких записей, если документаторам что-то непонятно, то они:
- спрашивают разработчиков (непосредственного автора);
- или архитектора/лида (человек знающий/догадывающийся, но сам непорседственно не писавшего код);
- или просто сами идут в код и разбираются;
- или забивают, и документация выходит как есть.


Great V.
> Нет. Вот моя позиция: код и документация это две сущности с общим предком.
правильно. Пототипирование.
Некоторые утилиты для пототипирования тебе и документацию (начальную) и код (начальный) состряпают.

#46
16:46, 16 мая 2019

Zab
Ты не прав. По пунктам:
> "У нас" это где? Такие порядки бывают, я тоже одно время работал в фирме с
> подобной организацией.
Обычная контора, которая разрабатывает корпоративный софт.

> Подобная разработка стоит раз в десять дороже традиционной.
Да, хорошая разработка стоит в 10 раз дороже, чем собрать прототип на коленке. Зато это будет протестированная разработка с нормальной документацией и саппортом.
За это и платят в 10 раз больше.

> В транзасе эти траты имели возможность переложить на заказчика, микрософт тоже может себе
> позволить, много еще таких богатеньких?
Почти все компании, где больше сотни (условно) разрабов. Иначе это просто хаос.

> Стоит еще добавить, что в такой системе плохо живется сотрудникам, способных вырабатывать технологии, там нужны
> послушные, а не умные.
Отлично живётся, я сам такой. Просто я уже на один шаг перешагнул и понимаю для чего всё это. Потому что сегодня ты с коллегой пилишь офигенное гениальное решение, а завтра коллега ушёл, а тебе из саппорта пишут, что у клиента есть баг и как его править никто не знает, т.к. твоё гениальное решение никто не понимает. И приходится самому своё время тратить. А пока к саппорту версия продукта придёт тебя ещё документаторы помучают, т.к. надо всё это понятно для клиентов описать. А если будет непонятно, то потом ещё и клиенты тебя мучить будут. Лучше уж я потрачу 4-6 часов, но нормально опишу фичу, тем более, что обычно к ней бывает техпроект, по которому её делали и там просто текст переносишь с небольшими изменениям, например убирая лишние варианты реализации.


> Зато весь процесс разработки предсказуем и контролируем
> администрацией.
Немного не так. У нас нет какого-то жёсткого контроля сверху. К нам на версию приходят фичи сверху, а мы решаем как это реализовывать в каком порядке и объёме. Никто не будет проверять, написал ты документацию или нет, сам же страдать потом будешь.

> Дорого, занудно, но надежно. И без перспектив удешевления,
> потому как система пресекает свою модернизацию.
Про модернизацию откровенно не понял. У нас наоборот всё довольно динамично меняется. По сути каждый год процесс разработки немного модернизируется/адаптируется, какие-то пункты выкидываем или переделываем, т.к. не удобно работать или наоборот что-то ещё добавляем. У нас аджайл и после каждого спринта есть ретро, можем прямо там что-то в процессе разработки поменять, если понимаем, что есть проблемы. И причём тут кто-то сверху вообще не участвует во всём этом, мы просто должны отдавать версию в конце проекта и ставить релизы на опытную эксплуатацию каждый спринт.

> Декларируется возможность модернизации специальными органами системы, но реально это плохо работает,
> слишком тяжеловесная конструкция выходит.
Это только для старых компаний характерно, современное айти так старается не работать.

#47
16:50, 16 мая 2019

Zab
> По идее, лиды и/или архитекторы и должны писать ту часть внутрипроектной
> документации, которая не очень то привязана к коду и лучше бы ее делать
> отдельно.
Сам пишешь внутрипроектную? или приходилось ли такой пользоваться?
если, да, то в каком формате (вики, ворд доки); где хранится, и какой доступ/обновление.

Zab
> Но тут важно найти границу, на которой оторванная от кода документация
> перестает быть полезной. Внутрипроектную документацию то пишут не просто так,
> кому-то она должна быть потенциально полезной.
на твоём опыте - кто следит(ил) за актуальностью документации? (те же лиды/архитеторы), или просто тот человек, который непорсдественно обращался к документу и говорил: "старо! надо обновить?"

#48
17:12, 16 мая 2019

skalogryz
> кроме примеров, к проектам идут тестовые приложения, и утилиты.
> (наличие "тестов" зависит от проекта. Обычно тесты нужны для библиотек и
> движков)
> Так что сам факт, того, что проект, это больше конечный продукт, а продукт +
> сопровождение к нему не должен никого пугать.
Мы тесты не поставляем, нет смысла, т.к. само API модифицировать клиенты не могут. Для API есть документация с примерами + есть небольшие учебные проекты каких-то модулей, которые мы поставляем по запросу.
Но у нас есть ещё прямая связь между клиентами и разработчиками. Есть форум, что-то типа StackOverflow, где разработчики клиентов задают вопросы по продуктам или API, если что-то непонятно из документации. Разработчики могут отвечать на такие вопросы (не обязаны конечно), либо саппорт старается.

skalogryz
> И кстати! тут важный момент.
> Документация это действительно под-проект конченого продукта.
> Потому что как и в коде, в документации могут быть ошибки. А ошибки принято
> исправлять, аналогично версиям софта.
> Т.е. в документации фиксируется версия (релиз). И если исправляют ошибки, или
> вносят изменения, но выпускается новая редакция.  (так делается по-уму)
Да, так и есть. У нас на документацию также оформляются дефекты, как и на сам продукт. И отдел документирования точно также их правит и выпускает с новой версией или сразу на сайте обновляет.

skalogryz
> не доросли в каком плане?
> моральном (трудно обучить документаторов/банальная лень/другие приоритеты)
> или
> организационном (нет людей, чтобы за всем этим следить или даже организовать)
Конкретно мой отдел не дорос по причине отсутствия особой необходимости. Т.е. изначально много лет назад мы сформировали скелет документации, нарастили на него "мясо", теперь уже не так много правок вносится, в основном по новым фичам. Документаторы в отдельном отделе работают, возможно у них есть какие-то системы контроля версий или что-то ещё, я не в курсе. Но вообще прицепить документацию к проекту мы бы хотели, банально чтобы согласование в том же git проходить, а не отдельным процессом.

skalogryz
> Организационный момент:
> Когда описывается функционал в вики, должны ли разработчики придерживаться
> каких-то стандартов. Или просто описывают, как могут.
Стандартов нет, это внутренняя документация. Пишем просто, чтобы понятно было. У нас после выпуска версии идёт её передача в поддержку, команда поддержки при приёме версии читает эту документацию и потом проходит аттестацию по изменениям версии. Если какие-то косяки в документации находятся, то обычно на этом этапе их оперативно правим. Ещё архиважная функция документации - она у нас по версиям хранится, и иногда возникает ситуация, когда в коде что-то написано странное, на первый взгляд ошибка, но как будто написано так специально. Мы определяем в какой версии был написан этот код, поднимаем документацию и разбираемся, почему было сделано именно так. Это не те случаи, когда в код можно HINT: добавить с описанием, это когда какое-то большое и непонятно решение в коде, которое вроде на первый взгляд перечит требованиям бизнеса.

> и при разборе таких записей, если документаторам что-то непонятно, то они:
> - спрашивают разработчиков (непосредственного автора);
> - или архитектора/лида (человек знающий/догадывающийся, но сам непорседственно
> не писавшего код);
Обычно к тимлиду идут, он сам уже пнёт в нужном направлении.

> - или забивают, и документация выходит как есть.
Такого не будет, т.к. документацию потом отправляют на рецензирование самим разработчикам :)

#49
17:17, 16 мая 2019

skalogryz
> Сам пишешь внутрипроектную? или приходилось ли такой пользоваться?
> если, да, то в каком формате (вики, ворд доки); где хранится, и какой доступ/обновление.
Всю жизнь пишу, кроме последних пяти лет, наверное.
В разных условиях, с разными внешними требованиями или вообще без них.
Чаще всего в ворде, но когда то давно и другими средствами пользовался, когда напрямую требовали их использования.
Много схем использую, рисую в основном в visio.
Доступ внутри фирмы обычно у всех желающих есть, но желающих читать документацию никогда не бывает много. Если человек десять пользуются - уже хорошо, но обычно их меньше.
Регулярное обновление обычно не проводится. Когда затеваются работы, затрагивающие какие-то старые элементы системы, тогда и обновляется ее описание, по моей инициативе или по сигналу от того, кому она потребовалась.
В обычном же режиме, существует одно описание, соответствующее состоянию до начала работ, и еще одно, сделанное по при их окончании. Чаще всего это два разных документа. При необходимости делаются минидокументы по изменениям.
Где хранится? Да где угодно. В общем доступе, естественно. В упорядоченном общем доступе, не мной определяемым. В каждой фирме обычно есть такой, туда просто встраиваешь свою часть информации.

> на твоём опыте - кто следит(ил) за актуальностью документации? (те же лиды/архитеторы)
Во многих случаях не следил никто. Не захотел бы я писать документацию, вообще бы без нее жили. И полезность ее не сразу осознавали, но потом подсаживались. Могу несколько случаев рассказать, достойных хождения в виде баек.
Но не везде так. В одном из мест, к примеру, в мои задачи вообще не входило написание кода, та самая внутренняя документация и была фиксацией результатов моей работы. Но документация никогда не была самоцелью, она писалась для облегчения работы, а не "чтобы была". Внутреннюю документацию то все равно никому видеть не положено, из непричастных к разработке.

#50
17:20, 16 мая 2019

Zab
> Но документация никогда не была самоцелью, она писалась для облегчения работы,
> а не "чтобы была". Внутреннюю документацию то все равно никому видеть не
> положено, из непричастных к разработке.
люди и начинают документацию писать, именно когда приходит "осознание" необходимости!

а потом и другие
Zab
> подсаживались
:)
(если не на писание, то на использование точно)

Мизраэль
спасибо, зафиксирую!

#51
17:28, 16 мая 2019

skalogryz
> люди и начинают документацию писать, именно когда приходит "осознание" необходимости
К сожалению это не так. Технари обычно не умеют писать, испытывают сплошной дискомфорт из за отсутствия даже минимального набора навыков, потому от написания всячески увиливают, даже если осознают необходимость.

#52
17:31, 16 мая 2019

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

а ещё помогают:
- наводящие вопросы
- копипаста из емейлов (или других средств общения, если такие используются).

#53
17:39, 16 мая 2019

skalogryz
Просто, у тебя проблем с оформлением мысли в текст нет, судя по качеству постов на форуме. Но у подавляющего большинства такие проблемы есть. Типа, "все понимает, а сказать не может". Хорошо еще, если понимает... сразу же не определишь, не является ли бред в высказываниях отражением бреда в мыслях.

#54
17:46, 16 мая 2019

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

#55
18:19, 16 мая 2019

Zab
> В системе образования же излагать вообще никак не учат
Писать "изложения" заставляют всех.
Просто почему-то упор делают на грамотность, а не на точность изложения и предачи сути.

Zab
> Просто, у тебя проблем с оформлением мысли в текст нет
> ...
> Если человека писать не учить, он дойдет до минимального уровня спустя лет десять графоманства.
вот это как раз за 10 лет графоманства!

Zab
> Но у подавляющего большинства такие проблемы есть. Типа, "все понимает, а
> сказать не может". Хорошо еще, если понимает... сразу же не определишь, не
> является ли бред в высказываниях отражением бреда в мыслях.
именно! написание документации описания как оно работает, это отличный способ проверки понимания (такая проверка важна для Лидов, чтобы они знали, что люди в команде понимают, а что нет)

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

Страницы: 1 2 3 4
ФлеймФорумПрограммирование

Тема в архиве.