Проблемы документирования software design

0 коммент. | добавить комментарий
Сегодня на постмортеме решали, как менять существующий процесс документирования дизайна. Проблемы очевидны:
  • дизайн-документы хранятся в морально устаревшем формате Word, низкая прозрачность
  • сложный шаблон документа как результат стремления покрыть все требования к дизайну из ASPICE L3 HIS scope
  • непонятно, актуально ли описание дизайна, или уже устарело - к коду доверия больше.
Как перестать писать дизайн "из-под палки" и что вообще делать - мне пока непонятно. Нашел вот цитату из David Parnas and Paul Clements. "A Rational Design Process: How and Why to Fake It" in Software State-of-the-Art: Selected Papers. Dorset House, 1990, pg. 353-355:


It should be clear that documentation plays a major role in the design process that we are describing. Most programmers regard documentation as necessary evil, written as an afterthought only because some bureaucrat requires it. They do not expect it to be useful.
This is a self-fulfilling prophesy; documentation that has not been used before it is published, documentation that is not important to its author, will always be poor documentation.
Most of that documentation is incomplete and inaccurate, but those are not the main problems. If those were the main problems, the documents could be easily corrected by adding or correcting information. In fact, there are underlying organizational problems that lead to incompleteness and incorrectness and those problems, which are listed below, are not easily repaired.
1) Poor Organization: Most documentation today can be characterized as "stream of consciousness" and "stream of execution." "Stream of consciousness" writing puts information at the point in the text that the author was writing when the thought occurred to him. "Stream of execution" writing describes the system in the order things will happen when it runs. The problem with both of these documentation styles is that subsequent readers cannot find the information they seek. It will therefore not be easy to determine that facts are missing, or to correct them when they are wrong. It will not be easy to find all the parts of the document that should be changed when the software is changed. The documentation will be expensive to maintain and, in most cases, will not be maintained.
2) Boring Prose: Lots of words are used to say what could be said by a single programming language statement, a formula, or a diagram. Certain facts are repeated in many different sections. This increases the cost of the documentation and its maintenance. More importantly it leads to inattentive reading and undiscovered errors.
3) Confusing and Inconsistent Terminology: Any complex system requires the invention and definition of new terminology. Without it the documentation would be far too long. However, the writers of software documentation often fail to provide precise definitions for the terms they use. As a result, there are many terms used for the same concept and many similar but distinct concepts described with the same term.
4) Myopia: Documentation that is written when the project is nearing completion is written by people ho have lived with the system for so long that they take major decisions for granted. They document the small details that they think they will forget. Unfortunately, the result is a document useful to people who know the system well, but impenetrable for newcomers.
Documentation in the ideal design process meets the needs of the initial developers as well as the needs of the programmers who come later. Each of the documents mentioned above records requirements or design decisions and is used as a reference document for the rest of the design. However, they also provide the information that the maintainers will need. Because the documents are used as reference manuals throughout the building of the software, they will be mature and ready to use in later work. The documentation in this design process is not an afterthought; it is viewed as one of the primary products of the project. Some systematic checks can be applied to increase completeness and consistency. [...]
"Stream of consciousness" and "stream of execution" documentation is avoided by designing the structure of each document. Each document is designed by stating the questions that it must answer and refining the questions until each defines the content of an individual section. There must be one, and only one, place for every fact that will be in the document. The questions are answered, i.e., the document is written, only after the structure of the document has been defined. When there are several documents of a certain kind, a standard organization is written for those documents. Every document is designed in accordance with the same principle that guides our software design: separation of concerns. Each aspect of the system is described in exactly one section and nothing else is described in that section. When documents are reviewed, they are reviewed for adherence to the documentation rules as well as for accuracy.
The resulting documentation is not easy or relaxing reading, but it is not boring. It makes use of tables, formulas, and other formal notation to increase the density of information. The organizational rules prevent the duplication of information. The result is documentation that must be read very attentively, but rewards its reader with detailed and precise information. [...]
No matter how often we stumble on our way, the final documentation will be rational and accurate. Even mathematics, the discipline that many of us regard as the most rational of all follows this procedure. [...] Analogous reasoning applies to software. Those who read the software documentation want to understand the programs, not relive their discovery. By presenting rationalized documentation we provide what they need.
Our documentation differs from the ideal documentation in one important way. We make a policy of recording all of the design alternatives that we considered and rejected. For each, we explain why it was considered and why it was finally rejected. Months, weeks, or even hours later, when we wonder why we did what we did, we can find out. Years from now, the maintainer will have many of the same questions and will find his answers in our documents.

Как стать ПМом

6 коммент. | добавить комментарий
За последние месяцы меня несколько раз спрашивали, что нужно для того, чтобы стать руководителем проекта (ПМ). Что примечательно, этот вопрос исходит в основном от джуниоров, молодых и амбициозных. Опуская сантименты "оно вам не надо" и т.д., попробую высказать свое субъективное и неправильное мнение на этот счет.

1. ПРИЧИНА

Главная причина того, что люди задаются таким вопросом - стремление к власти. Ничего плохого в этом нет - как известно, главных испытаний в жизни всего 4: деньги, слава, власть и любовь. Для точки внутри пространства такого ортогонального базиса, например, жажда любви ничем не лучше жажды власти. К тому же, сравните:
  • "я зарабатываю пять тысяч в месяц" (деньги),
  • "меня знают и уважают в Одессе" (слава),
  • "я руковожу тремя проектами и сорока людьми" (власть).
Что звучит убедительней? Власть, только она наиболее полно позволяет человеку ощутить степень своего карьерного роста и практически количественно (в подчиненных) измерить его.

2. СРЕДСТВА

Теперь о средствах достижения вожделенного ПМства. В дополнение к очевидному - желанию стать ПМом - более-менее внятно озвучить я могу пять:

2.1. Опыт. Я придерживаюсь мнения, что стать хорошим ПМом, не отработав N лет в инжиниринге, нельзя. Плохим - можно, но мы не рассматриваем этот вариант по причине того, что все риски, связанные с плохим ПМом, разделяет его руководитель, а значит вряд ли назначит его на эту должность. Только через годы работы разработчиком, старшим разработчиком, техлидом и тимлидом можно приблизиться к креслу ПМа, поскольку:
  • позиция разработчика даст вам прочувствовать то, как управлять собой и своим временем
  • позиция старшего разработчика поможет вам глубже разобраться в областях, непосредственно не относящихся к кодингу: анализ и управление требованиями, оценка трудозатрат, ревью архитектуры и дизайна и т.д. Кроме того, обычной практикой является курирование старшим разработчиком одного или нескольких программистов.
  • на позиции тим/тех-лида в первую очередь приходит понимание того, что такое ответственность за команду. Это очень важный пункт, который нельзя пропускать, поскольку через него мы приходим к умению нести ответственность за технические решения (свои и команды), организационные решения (свои и компании), ну и в целом за проект. Кроме этого, здесь вам придется научиться управлению рисками и проблемами, грамотному общению с заказчиком, а также основам того, как быть интерфейсом между командой, компанией (рекрутерами, HR, руководством, администрацией) и заказчиком.
К сожалению или к счастью, опыт здесь нельзя заменить знаниями. Разработчик, прослушавший курсы по управлению проектами, - это еще не ПМ. В системном анализе программные проекты относятся к классу сложных систем (СС) с неформализуемыми компонентами (в первую очередь - людьми). Управление ожиданиями подчиненных, понимание культурных и личностных особенностей разных заказчиков, понимание и принятие правил, по которым функционирует ваша организация (а также их выполнение) - все это нельзя получить из книг. Более того, даже формализуемые компоненты СС (собственно ПО) также требуют опыта. Например: никому не нужен в качестве архитектора вчерашний студент, пусть и очень знающий, но не спроектировавший N реальных систем с учетом требований производительности, масштабируемости, устойчивости к изменениям требований и т.д. - а ПМ должен выполнять ревью требований, архитектуры, тест-плана, поэтому и спрос с него соответствующий.

2.2. Процессная дисциплина. Только понимая процессные активности той или иной процессной модели, принимая их для себя и выполняя их, можно внедрять и контролировать их выполнение в проекте. Сюда я отношу создание технических требований, оценку трудозатрат, управление рисками, своевременную эскалацию проблем, управление изменениями, аккуратную и регулярную, как чистка зубов, отчетность. Из относящихся к кодированию: код-ревью и создание юнит-тестов. На всем этом нужно набить шишки, находясь на позиции старшего разработчика, поскольку те же шишки на позиции ПМа будут стоить гораздо дороже - как вам, так и компании. См. также пункт 2.1.

2.3. Инициатива (или "делайте больше"). Покажите своему руководителю (от которого зависит ваше повышение), что вы можете больше. Вам дали задачу? Найдите способ сделать ее лучше, чем указано в требованиях! Заложите больше масштабируемости, проведите рефакторинг, напишите больше тестов, оптимизируйте алгоритм. Однако, не бросайтесь с места в карьер: отсутствие опыта приведет только к тому, что вы будете предлагать нереализуемые, ненужные или ранее отвергнутые сценарии и тем самым злить начальство. См. также пункт 2.1.

2.4. Язык. Как правило - английский. ПМ, пишущий письма заказчику на плохом английском, с ошибками в словах и грамматике, отвратителен. С другой стороны, вполне можно писать простыми предложениями, употреблять в основном часто используемые слова - но ради Бога, грамотно! Оценить свою степень владения языком можно на курсах, у преподавателя, у более знающего коллеги, а также, частично, с высоты своего языкового опыта. См. также пункт 2.1.

2.5. Способности к руководству. Это что-то из области "можно вам доверить людей" или нет. Оценивать вас по этому пункту будет ваш руководитель, скорее всего, чисто субъективно, в связи с чем ограничусь примерами:
  • "человек-фюрер", как правило, отлично справляется со всеми задачами, возложенными на него, и при этом (простите мой французский) аж ссытся, так хочет кем-нибудь поруководить. Обычно не упускает возможности дать коллегам понять, что главный здесь - он, а также зарисоваться перед начальством. Такому человеку доверять руководство людьми опасно - у него нет к этому природных способностей, и частично помочь здесь сможет специализированное обучение, опыт и внутренняя дисциплина.
  • "человек-рыба" также хорошо выполняет все поставленные задачи, но другими людьми склонен не интересоваться, не заинтересовывать, не развивать. Обычно стремится большой объем работы выполнить сам, мотивируя тем, что у команды мало опыта. Такому человеку доверить руководство также можно только после предварительных упражнений.
Я бы мог перечислить еще много смешных типажей, но это - тема отдельного поста. Хорошее упражнение - попробовать посмотреть на свое поведение в офисном ареале со стороны, непредубежденным взглядом. Очень важно понимать свои недостатки в этой области, иногда они - причина того, почему вас не повышают. Как правило, с ними вам придется бороться на протяжении всей карьеры, поскольку они (в отличие от предыдущих четырех пунктов) - часть вашей личности. Вы хотите руководить людьми до судорог в коленках? Скрывайте силу вашего желания, не дайте никому догадаться! Вы уверены, что знаете все лучше всех? Превозмогите себя, дайте вашим коллегам шанс - пусть они сделают не так идеально, но зато приобретут опыт, и т.д.


3. ОТКЛОНЕНИЯ

Иногда на ПМских позициях оказываются люди, не соответствующие написанному выше. Причин у этого может быть несколько:
  • повышение произвел некомпетентный руководитель. Либо он (руководитель) пострадает из-за этого и отменит такое повышение, либо ПМ "натыркается" и будет сносно выполнять свои ежедневные обязанности, тем не менее лажаясь каждый раз, когда от него потребуется что-то, что выходит за круг его привычных задач (написать proposal для нового заказчика, выступить с презентацией на ежегодном собрании и т.д.)
  • повышение произвел компетентный руководитель. В этом случае он (руководитель) принимает все риски, связанные с таким назначением, и возможно выполняет часть работ за своего ПМа. Такая ситуация возможна, когда:
    • руководитель держит бразды правления в своих руках, отдавая ПМу рутинные технические задачи (распределение тасков между людьми, сбор индивидуальных отчетов и подготовка проектного отчета, написание / ревью технических требований и т.д.) О реальной власти ПМа в такой ситуации речь не идет - однако это может быть ловко замаскировано более опытным руководителем и подано молодому ПМу под правильным для него соусом из манипулятивных утверждений и обещаний.
    • Другой вариант развития событий: руководителю нужен реальный ПМ, нанимать "готового" с рынка для компании экономически нецелесообразно, поэтому новый ПМ целенаправленно взращивается в реальных условиях. Это возможно при соблюдении требований 2.2, 2.3, [2.4], 2.5 из списка выше. При этому руководитель ПМа все так же несет ответственность за проект, готов придти ему на помощь в случае необходимости и в целом верит в него.
  • компания понимает под ПМом что-то принципиально другое, чем то, что понимаю я. Мне встречались случаи, когда ПМами называли себя фактические продакт-менеджеры, сейлзы или аналитики. Скорее всего, ПМ в таком случае будет бесконечно далек от PMBOK.

4. ВЫВОДЫ

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

Иногда можно увидеть в кресле ПМа дятла. Несмотря на то, что этому, как правило, можно найти объяснение, ответьте себе на вопрос: а вы - дятел? При желании можно придумать, как нацепить на себя лейбу ПМа, что будет служить формальным подтверждением вашей власти. Однако власть - это всего лишь одна из мер карьерного роста, и лейба ПМа не заменит содержания ПМа. Быть хорошим ПМом в средне- и долгосрочной перспективе гораздо выгодней, чем плохим:
  • вы не теряете связи с инжинирингом, который развивается очень быстро
  • вы сможете больше делать, брать на себя больше ответственности, ваша работа будет интересней
  • вы не теряете возможности повышения зп. Хороший ПМ развивается на своей должности, плохой - держится за нее и за свой узкий круг обязанностей, внутри которого он чувствует себя комфортно, а снаружи - нет
  • хороший ПМ пользуется уважением коллег, плохой - нет, его обсуждают за глаза, из-за него достается на орехи начальству
  • у плохого ПМа нет перспективы роста (количества подчиненных, получения новых проектов и т.д.).
В общем-то, можно быть и дятлом в кресле ПМа. Главное - не обманывать себя. Удачи!