Придуманная история
В один прекрасный вечер шеф вызывает меня на ковёр и повествует о том, что проект уже почти готов, что ему надо общаться с инвесторами, а показывать - нечего. При этом убедительно доказывая, что программный код никто смотреть не будет, а подавай аналитикам и инвесторам хорошо написанную, структурированную и оформленную документацию. В общем, обычная офисная история. И весь трагизм ситуации в том, что шеф в этот раз оказался прав....
В общем, с унылым видом я вышел из его кабинета, рассуждая о том, сколько времени и нервов займёт сей труд, и насколько теперь кодирование отстанет от графика. На памяти был прошлый опыт написания документации для предыдущего проекта. В тот раз мы решили использовать Microsoft Word для оформления документации и по полной огребли проблемы с конвертированием в распространённые форматы, поддержанием структуры документа и оформлением внешнего вида. Наученная горьким опытом, наша команда решила начать написание документации с её проектирования.
Прежде всего, мы решили отделить информацию от её представления. Несмотря на то, что в прошлый раз мы использовали стили, программисту Николаю таки пришлось задержаться после работы, чтобы отредактировать 150 страниц вордовского текста, после того как по какой-то, одному Богу известной причине, у документа "слетели" стили.
На внеочередной планёрке мы решили использовать базу данных для хранения информации и какой-либо генератор отчётов, для построения документации на основе этой базы данных. После непродолжительной дискуссии большинство проголосовало за базу данных на основе MicrosoftAccess. Что касается выбоа генератора отчётов, то мы решили использовать FastReport, лицензия на который у нас осталась с предыдущего, кстати сказать - успешного, проекта, который был связан с генерацией финансовой отчётности.
Итак, выбор был сделан, и нам предстояло представить структуру документации на бумаге. Прежде всего, нам предстояло описать протоколы, которые поддерживает
наша система. Каждый протокол поддерживает некий набор функций. В свою очередь, каждая функия имеет некоторый набор параметров. Необходимо было описать все протоколы, функции и параметры. Как говорится - глаза боятся, а руки делают. Была создана база данных, а в ней три таблицы - таблица протоколов, таблица функций и таблица аргументов.
Первым делом мы заполнили таблицу протоколов, благо их было не много. Первым порывом было увидеть это на бумаге. Мы не стали отказывать себе в удовольствии и построили простейший отчёт при помощи встроенного в FastReport мастера отчётов. Возможно, здесь сыграл свою роль дизайнерский талант автора FastReport, но этот простейший отчёт нам весьма понравился.
Поскольку хранить описание всех методов всех протколоов мы решили хранить в одной таблице, то следующим шагом мы привязали таблицу описания методов к таблице описания протоколов по её ключу и заполнили таблицу всеми методами одного протокола. Благо, Microsoft Access оказал в этом помощь, предоставляя удобный интерфейс редактирования связанных данных. На это раз ситуация повторилась - мы хотели убедиться что пошли по правильному пути и снова взяли в руки FastReport. На этот раз мастер создания отчётов нам не смог помочь, поэтому пришлось вооружаться мышкой и описанием FastReport. Вскоре, нам удалось во встроенном дизайнере добавить новую таблицу в отчёт, используя ADO Query объект. Немногим больше времени заняло создания бэнда детализации, который мы привязали к основному бэнду. То есть мы построили отчёт Master-Detail. Построение отчёта заняло немногим более секунды и нашим глазам предстал документ, в котором уже был виден будущий прототип новой спецификации. Не буду подробно останавливаться на том, как мы вносили данные, скажу лишь, что таблица с описанием аргументов была аналогичным образом привязана к таблице с опсанием методов. Microsoft Access легко и непринуждённо справился с тремя уровнями вложенности, за что мы были несказанно благодарны разработчикам Майкрософт. Не вызвало проблем и добавление в шаблон отчёта бэнда Subdetail с описанием аргументов. Наш отчёт уже явно принял форму профессионального документа, как по форме, так и по содержанию.
Наш коллектив поручил мне отнести распечатку полученного документа шефу для одобрения. Каково же было моё удивление, когда шеф после минутного ознакомления вернул распечатку с приказом добавить титульный лист и схему документа. С титульным листом проблем не возникло, он был добавлен и без чтения документации. Что касается схемы документа... По прошлому опыту мы знали, что Microsoft Word повзоляет строить схему документа автоматически, на основе стилей. Непродолжительное изучение документации FastReport открыло нам секрет богатых возможностей по автоматической генерации схемы отчёта. Проблема была решена в течение нескольких минут и меня снова отправилии на ковер к шефу. В этот раз изучение документа было долгим и пристальным и я в нерешительности переминался с ноги на ногу, пока шеф листал страницы. На этот раз его лицо выражало благодушность и он сообщил что «В общем, документ ему понравился, но не хватает нескольких вещей». На этот раз он поведал, что сухие перечисления протоколов, функций и аргументов могут оказать положительное воздействие на аналитиков только в случае, если они подкреплены соответствующими схемами и диаграммами. При этом он прочитал получасовую лекцию об особенностях человеческого восприятия и преимуществе графического представления информации. В общем, он сел на своего любимого конька и был самим собой. Результатом его монолога было задание добавить несколько схем и диаграмму (кстати, это не для печати, но данные для диаграммы он придумал сам).
В очередной раз я понуро вышел из его кабинета. Работать не хотелось и меня всего переполняла злость на шефа. Попутно я запустил дизайнер отчётов и начал рисовать стрелочки и квадратики, попутно раскрашивая их в разные цвета. Эта «игра» постепенно начала успокаивать нервы а на экране начало вырисовываться нечто похожее на схему. Поиграясь часик с дизайнером, я получил желаемую схему, при этом даже не заметив как это произошло. Следующие схемы были созданы по образу и подобию первой. При этом я полюбил инструмент копирования формата.
Для построения диаграммы, пришлось «скормить» данные, придуманные шефом, в отдельную таблицу. Как и со всем остальным, разбираться долго не пришлось - помог встроенный в FastReport модуль построения диаграмм. Немного повозившись, были получены (а местами и подогнаны) графики.
Человек такое существо, что быстро ко всему привыкает. Следующий поход к шефу был, хоть и не весьма приятный, но уже не было страха перед его новыми требованиями. На этот раз лицо шефа уже было довольным. Бегло просматривая документ и разговаривая по телефону, он заметил. «Так-так, весьма неплохо. Кстати, сколько раз вы редактирвали документ?», а в его глазах светилась усмешка. Не дав мне опомниться, он вдруг сказал: «А где история редактирования документа?!! Продукт ещё не готов, некоторые протоколы могут быть расширены или дополнены, как мне ориенторваться в этом?» При этом он показывал пальцем на кипу бумаги, на которой были распечатаны предыдущие версии документов.
В общем, в большой спешке были добалена новая таблица в базу данных, содержащая историю редактирования документа и в шаблон отчёта добавлен новый лист, на котором помещался отчёт Document Revision History.
Чтобы не предстать в невыгодном свете, заметим, что некоторые вещи в документ были добавлены не по приказу шефа, а по инициативе нашей команды. Уже после вышеприведённых событий, мы отредактировали базу данных, связав её с ещё одной таблицей, в которой мы поместили описание типов данных аргументов.
История будет не полной, если не рассказать что при построении отчёта мы всё-таки нашли некоторые «особенности» FastReport. К чести разработчиков сказать, наши пожелания были учтены довольно быстро - служба поддержки отвечала быстро и по существу. Но это, говорят, как повезёт - зависит от времени года, времени суток и дрейфа айсбергов в Северном Ледовитом океане.
Но это ещё не конец истории. Документация всё-таки попала на стол аналитиков и первым вопросом было: «А чем в ваших протоколах отличаются входные параметры от выходных?». Говорят, когда шеф услышал этот вопрос, то он густо покраснел и сделал один звонок. Звонок был Вашему покорному слуге. Не буду передавать содержание этого монолога, скажу лишь одно - спасибо тебе, Господи, за то что ты дал людям электронную почту. В срочном порядке в таблицу было добавлено новое поле, определяющее принадлежность каждого аргумента ко входному или выходному параметру. В отчёт был вставлен бэнд группировки по новому полю и отчёт принял вид, который и используется нашей компанией и нашими клиентами по настоящее время.
Резюмируя, хочу сказать, что в следующий раз наша команда не будет размышлять над тем, какое решение выбрать для описания форматов протоколов. Полученный опыт однозначно показал преимущества разделения информации от её представления. Как в плане трудозатрат для получения результата, так и в плане качества. Помимо этого нам удалось сэкономить на дополнительных инструментах по конвертирования документации из формата MS Word, в широко распространённые форматы представления данных, а это немалые суммы - наша компания не использует нелицензионное программное обеспечение.
P.S.
И все-таки прав был шеф насчёт «Истории исправления документа», уже не раз наc выручала эта возможность. А продукт наш успешно развивается вместе с документацией. Теперь вот у шефа новый бзик - когда узнал, что фастрепорты выпустили сервер, захотел чтобы для наших партнёров в сети всегда лежала самая свежие версия доки. Хочет нашу спецификацию под FR сервер перетащить, как думаете, имеет смысл?
В общем, с унылым видом я вышел из его кабинета, рассуждая о том, сколько времени и нервов займёт сей труд, и насколько теперь кодирование отстанет от графика. На памяти был прошлый опыт написания документации для предыдущего проекта. В тот раз мы решили использовать Microsoft Word для оформления документации и по полной огребли проблемы с конвертированием в распространённые форматы, поддержанием структуры документа и оформлением внешнего вида. Наученная горьким опытом, наша команда решила начать написание документации с её проектирования.
Прежде всего, мы решили отделить информацию от её представления. Несмотря на то, что в прошлый раз мы использовали стили, программисту Николаю таки пришлось задержаться после работы, чтобы отредактировать 150 страниц вордовского текста, после того как по какой-то, одному Богу известной причине, у документа "слетели" стили.
На внеочередной планёрке мы решили использовать базу данных для хранения информации и какой-либо генератор отчётов, для построения документации на основе этой базы данных. После непродолжительной дискуссии большинство проголосовало за базу данных на основе MicrosoftAccess. Что касается выбоа генератора отчётов, то мы решили использовать FastReport, лицензия на который у нас осталась с предыдущего, кстати сказать - успешного, проекта, который был связан с генерацией финансовой отчётности.
Итак, выбор был сделан, и нам предстояло представить структуру документации на бумаге. Прежде всего, нам предстояло описать протоколы, которые поддерживает
наша система. Каждый протокол поддерживает некий набор функций. В свою очередь, каждая функия имеет некоторый набор параметров. Необходимо было описать все протоколы, функции и параметры. Как говорится - глаза боятся, а руки делают. Была создана база данных, а в ней три таблицы - таблица протоколов, таблица функций и таблица аргументов.
Первым делом мы заполнили таблицу протоколов, благо их было не много. Первым порывом было увидеть это на бумаге. Мы не стали отказывать себе в удовольствии и построили простейший отчёт при помощи встроенного в FastReport мастера отчётов. Возможно, здесь сыграл свою роль дизайнерский талант автора FastReport, но этот простейший отчёт нам весьма понравился.
Поскольку хранить описание всех методов всех протколоов мы решили хранить в одной таблице, то следующим шагом мы привязали таблицу описания методов к таблице описания протоколов по её ключу и заполнили таблицу всеми методами одного протокола. Благо, Microsoft Access оказал в этом помощь, предоставляя удобный интерфейс редактирования связанных данных. На это раз ситуация повторилась - мы хотели убедиться что пошли по правильному пути и снова взяли в руки FastReport. На этот раз мастер создания отчётов нам не смог помочь, поэтому пришлось вооружаться мышкой и описанием FastReport. Вскоре, нам удалось во встроенном дизайнере добавить новую таблицу в отчёт, используя ADO Query объект. Немногим больше времени заняло создания бэнда детализации, который мы привязали к основному бэнду. То есть мы построили отчёт Master-Detail. Построение отчёта заняло немногим более секунды и нашим глазам предстал документ, в котором уже был виден будущий прототип новой спецификации. Не буду подробно останавливаться на том, как мы вносили данные, скажу лишь, что таблица с описанием аргументов была аналогичным образом привязана к таблице с опсанием методов. Microsoft Access легко и непринуждённо справился с тремя уровнями вложенности, за что мы были несказанно благодарны разработчикам Майкрософт. Не вызвало проблем и добавление в шаблон отчёта бэнда Subdetail с описанием аргументов. Наш отчёт уже явно принял форму профессионального документа, как по форме, так и по содержанию.
Наш коллектив поручил мне отнести распечатку полученного документа шефу для одобрения. Каково же было моё удивление, когда шеф после минутного ознакомления вернул распечатку с приказом добавить титульный лист и схему документа. С титульным листом проблем не возникло, он был добавлен и без чтения документации. Что касается схемы документа... По прошлому опыту мы знали, что Microsoft Word повзоляет строить схему документа автоматически, на основе стилей. Непродолжительное изучение документации FastReport открыло нам секрет богатых возможностей по автоматической генерации схемы отчёта. Проблема была решена в течение нескольких минут и меня снова отправилии на ковер к шефу. В этот раз изучение документа было долгим и пристальным и я в нерешительности переминался с ноги на ногу, пока шеф листал страницы. На этот раз его лицо выражало благодушность и он сообщил что «В общем, документ ему понравился, но не хватает нескольких вещей». На этот раз он поведал, что сухие перечисления протоколов, функций и аргументов могут оказать положительное воздействие на аналитиков только в случае, если они подкреплены соответствующими схемами и диаграммами. При этом он прочитал получасовую лекцию об особенностях человеческого восприятия и преимуществе графического представления информации. В общем, он сел на своего любимого конька и был самим собой. Результатом его монолога было задание добавить несколько схем и диаграмму (кстати, это не для печати, но данные для диаграммы он придумал сам).
В очередной раз я понуро вышел из его кабинета. Работать не хотелось и меня всего переполняла злость на шефа. Попутно я запустил дизайнер отчётов и начал рисовать стрелочки и квадратики, попутно раскрашивая их в разные цвета. Эта «игра» постепенно начала успокаивать нервы а на экране начало вырисовываться нечто похожее на схему. Поиграясь часик с дизайнером, я получил желаемую схему, при этом даже не заметив как это произошло. Следующие схемы были созданы по образу и подобию первой. При этом я полюбил инструмент копирования формата.
Для построения диаграммы, пришлось «скормить» данные, придуманные шефом, в отдельную таблицу. Как и со всем остальным, разбираться долго не пришлось - помог встроенный в FastReport модуль построения диаграмм. Немного повозившись, были получены (а местами и подогнаны) графики.
Человек такое существо, что быстро ко всему привыкает. Следующий поход к шефу был, хоть и не весьма приятный, но уже не было страха перед его новыми требованиями. На этот раз лицо шефа уже было довольным. Бегло просматривая документ и разговаривая по телефону, он заметил. «Так-так, весьма неплохо. Кстати, сколько раз вы редактирвали документ?», а в его глазах светилась усмешка. Не дав мне опомниться, он вдруг сказал: «А где история редактирования документа?!! Продукт ещё не готов, некоторые протоколы могут быть расширены или дополнены, как мне ориенторваться в этом?» При этом он показывал пальцем на кипу бумаги, на которой были распечатаны предыдущие версии документов.
В общем, в большой спешке были добалена новая таблица в базу данных, содержащая историю редактирования документа и в шаблон отчёта добавлен новый лист, на котором помещался отчёт Document Revision History.
Чтобы не предстать в невыгодном свете, заметим, что некоторые вещи в документ были добавлены не по приказу шефа, а по инициативе нашей команды. Уже после вышеприведённых событий, мы отредактировали базу данных, связав её с ещё одной таблицей, в которой мы поместили описание типов данных аргументов.
История будет не полной, если не рассказать что при построении отчёта мы всё-таки нашли некоторые «особенности» FastReport. К чести разработчиков сказать, наши пожелания были учтены довольно быстро - служба поддержки отвечала быстро и по существу. Но это, говорят, как повезёт - зависит от времени года, времени суток и дрейфа айсбергов в Северном Ледовитом океане.
Но это ещё не конец истории. Документация всё-таки попала на стол аналитиков и первым вопросом было: «А чем в ваших протоколах отличаются входные параметры от выходных?». Говорят, когда шеф услышал этот вопрос, то он густо покраснел и сделал один звонок. Звонок был Вашему покорному слуге. Не буду передавать содержание этого монолога, скажу лишь одно - спасибо тебе, Господи, за то что ты дал людям электронную почту. В срочном порядке в таблицу было добавлено новое поле, определяющее принадлежность каждого аргумента ко входному или выходному параметру. В отчёт был вставлен бэнд группировки по новому полю и отчёт принял вид, который и используется нашей компанией и нашими клиентами по настоящее время.
Резюмируя, хочу сказать, что в следующий раз наша команда не будет размышлять над тем, какое решение выбрать для описания форматов протоколов. Полученный опыт однозначно показал преимущества разделения информации от её представления. Как в плане трудозатрат для получения результата, так и в плане качества. Помимо этого нам удалось сэкономить на дополнительных инструментах по конвертирования документации из формата MS Word, в широко распространённые форматы представления данных, а это немалые суммы - наша компания не использует нелицензионное программное обеспечение.
P.S.
И все-таки прав был шеф насчёт «Истории исправления документа», уже не раз наc выручала эта возможность. А продукт наш успешно развивается вместе с документацией. Теперь вот у шефа новый бзик - когда узнал, что фастрепорты выпустили сервер, захотел чтобы для наших партнёров в сети всегда лежала самая свежие версия доки. Хочет нашу спецификацию под FR сервер перетащить, как думаете, имеет смысл?