Best Practices по документации




В теме 15 ответов, и 9 участников, последнее обновление сделано пользователем Аватар (tilya) tilya 5 г, 11 мес. назад.

Показано 15 ответов - от 1 до 15 (всего 16)
  • Автор
    Сообщения
  • 20.03.2010 в 20:33 # 5756
    В принципе, ветка коррелирует с темой про шаблоны. Ведь в шаблонах обычно собраны эти самые лучшие практики (best practices), но всё же, есть ещё советы и гайды по составлению, которых в самих шаблонах обычно нет.
    А давайте здесь пособираем разные фишки, советы, best practices по составлению документов. Я думаю речь в основном пойдет по SRS, но я специально решил сделать тему более общей.
    Поделиться:

    Цитировать

    06.05.2010 в 15:58 # 5757
    Аватар (Belle Morte)
    Belle Morte
    Админ
    Я, пожалуй, начну.

    Специфика нашего текущего проекта такова, что новые фичи добавляются довольно часто и их много. Есть одна главная высокоуровневая спецификация и много маленьких, каждая из которых описывает отдельный функционал. Чтобы как-то унифицировать процесс и не упускать ничего при добавлении такой фичи, мы написали короткий документ (2 страницы) — New Functionality Checklist. В нем по пунктам расписывается, какие моменты обязательно должны быть указаны в спецификации по новому функционалу, например, такие:

    1) Название страницы (если добавляется новая страница) в окне браузера (как ни странно, это то, о чем часто забывают аналитики и, соответственно, не делают программисты)
    2) Место новой страницы в Site Map диаграмме (если такая есть)
    3) Permissions (если они будут добавляться)
    4) Условия видимости и доступности нового функционала (если такие есть, помимо permissions)
    5) Специфические термины (если такие есть)

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

    Поделиться:

    Цитировать

    11.05.2010 в 22:02 # 5758
    Да, это отличная практика и я ее полностью поддерживаю по всем статьям :wink:
    Я поделюсь, как мне недавно порекомендовали, гораздо более мелкой фишкой.
    Всем, кто пишет документы с нуля (не генерируя их, к примеру, на постоянной основе из Requirement Management Tools) наверняка приходится следить за актуальностью динамических элементов в ворде (e.g. содержание, нумерация рисунков, таблиц, автотекст и т.д.). Абсолютное большинство этих элементов приходится обновлять вручную по завершению работы над документов (ну или вероятно можно поставить автообновление — вот только я не знаю как :) ).
    Так вот, полезное сочетание клавиш в ворде, которое стоит поставить себе в привычку - Ctrl + A (выделить все), затем F9 (обновить). После этого содержание, нумерация элементов, текст, колонтитулы — все будет обновлено. Честно говоря, мне, узнавшему об этой фишке слишком поздно, стало как-то обидно за кучу потраченного ранее времени :) .
    Поделиться:

    Цитировать

    12.05.2010 в 08:58 # 5759
    Аватар (bustor)
    bustor
    Подписчик
    Колонтитулы (header и footer) не обновятся при таком подходе — надо войти в режим редактирования колонтитулов и сделать Ctrl+A и F9.

    Кроме того, если в документе есть несколько секций (section), то делать Ctrl+A и F9 надо в каждой секции — и в основном тексте, и в колонтитулах.

    Поделиться:

    Цитировать

    08.06.2010 в 16:25 # 5760
    Аватар (Anna)
    Anna
    Подписчик
    Очень полезную методику для себя обнаружила в книге Effective Prototyping (спрашивается, причем тут прототипирование, если речь о СРС). Там приводились шаблоны для traceability требований и их приоритезации для дальнейшего отображения на прототипе (слегка подточив их под себя, можно использовать в крупных проектах, где фич много и изменяются они часто):
    1. Создается таблица сродни Acceptance Matrix — туда вписываются ID требований, стр в СРС, краткое описание, дата валидации, дата изменения, что изменилось, кто инициировал и т.д. (не суть, каждый для себя может определить набор информации, нужный ему в зависимости от ситуации);
    2. Данная таблица поддерживается по мере необходимости на протяжении всего проекта с указанием также информации о реализации и приемке.
    Удобно, я считаю, и наглядно. Вот линка на саму книгу: http://effectiveprototyping.com/ep_swmakers.shtml
    Поделиться:

    Цитировать

    04.08.2010 в 19:08 # 5761
    Добавлю еще несколько интересных и полезных фишек и способов использования MS Office, которые вероятно не знакомы начинающему пользователю (или про них успешно забывают, так и не внедрив в практику.. хотя стоило бы подумать).
    Здесь только то, что я лично использую в повседневной работе и нахожу очень удобным.

    1. Стили (Styles). Вы вероятно использовали стандартные офисные стили типа Heading 1, Heading 2 и т.д. для быстрого форматирования документа. Если у вас есть некий корпоративный шаблон, по которому вы пишете документацию, то советую подумать над добавлением свои стилей в кастомный Style Set. Делается это крайне быстро (выделяете блок текста, далее Save as New Style в панели стилей, там же создаете стайл сет), зато эффект весьма значительный. У меня есть свой Style Set с хедерами 4 уровней и обычным текстом (шрифт, отступы, межстрочные интервалы, абзацы и т.д.). Теперь блок текста в любом документе я форматирую в нужном мне ключе всего одним кликом.

    2. Расширенный поиск по тексту. Наверняка не все знают, что MS Word умеет искать не только блоки текста, но еще и форматирование. Пример полезного использования: у нас уже устоялась традиция все последние изменения в документе выделять красным шрифтом. Теперь представьте, насколько тяжелой становится работа по инкрементации версии спецификации очередным аналитиком, ведь необходимо пролистать огромный документ, вручную отыскивая "красные" места.
    Так вот — если вы вызовете окно поиска, затем тисните More внизу, то увидите опции для задания формата. В случае выше подходящим решением будет искать "пустой" текст (ничего не заполняете в поле Find What:) красным шрифтом.

    3. Format Painter. Убедительно советую — привыкните к этой фиче! Для тех, кто не сталкивался — в 2010 офисе это значок кисточки в правом верхнем углу панели Home (если не ошибаюсь, в 2007 она находится там же). Выделяете абзац, слово, часть таблицы, ячейки (Excel), фигуру/рисунок (особенно удобно в PowerPoint), жмякаете Format Painter и затем просто выделяете то, что вы хотите отформатировать в таком же ключе. Я уже честно говоря отвык использовать стандартные способы форматирования шрифтов, таблиц и т.д. — теперь просто копирую форматирование от абзаца к абзацу.
    P.S. А если кликнуть на Format Painter дважды, можно отформатировать несколько элементов последовательно.

    4.Форматирование при копировании-вставке. Меня часто бесило, когда я копирую в документ текст из любого другого места (допустим из веб-страницы). Потом приходится его нудно форматировать в духе остального текста (а можно еще Format Painter юзать :wink: ). Так вот, в 2010 ворде (и возможно в 2007 — нет возможности перепроверить) есть такая фишка, как Paste Options. Как только вы вставили текст в док, вы должны сразу увидеть всплывшее мини окошко около текста с опциями вставки. Я обычно выбираю крайнюю левую опцию — Keep Text Only. Это приводит вставленный текст к формату текста, который шел до этого (работает в 95 случаях из ста).

    5. Перенос заголовков таблиц на новую страницу. Я думаю, все сталкивались с ситуацией, когда таблица разрастается настолько, что занимает более чем одну страницу. И даже маленькие таблицы при смещении текста могут разносится по нескольким страницам. Довольно неплохой практикой считается отображение заголовка на каждой странице, дабы пользователь не скроллил в начало таблицы, чтобы посмотреть названия колонок. Делается это просто: выделяется ряд таблицы, являющийся хедером; кликаем правой кнопкой мышки — Table Properties -> вкладка Row; выставляем галочку Repeat as header row at the top of each page. Красота.. :)

    6. Удаление строк таблицы. Я долго мучился с удалением строк таблиц в MS Word, пока не нашел быстрое решение — 1) выделяете всю строку (для этого курсор подводите чуть левее самой левой ячейки желаемой строки, пока он не превратиться в стрелку, и кликаете левой кнопкой) и 2) жмякаете Shift + Del.

    7. Spell Checker. Почему не нужно пренебрегать его использованием, тут писать не буду — думаю, это и так понятно. Как его использую я: у меня практически нет красных и зеленых подчеркиваний в документе, потому что я постоянно обновляю словарь офиса путем добавления новых терминов. Представьте, что вы разрабатываете продукт, в документации на который много специфичных терминов. У вас будет либо рябить в глазах от красного и зеленого, либо вы просто будете эти предупреждения игнорировать. Не ленитесь — добавьте все эти термины в словарь, делается это не так уж и сложно. Зато (!) если вы в документах будете видеть, что Spell Checker на что-то ругается, вы это никогда не пропустите. Плюс, зеленые подчеркивания (синтаксические ошибки) не всегда по сути являются ошибками. Но я все равно стараюсь перефразировать предложение, если вижу, что Ворду это чем-то не нравится. Таким образом я себя приучил к тому, что любое предупреждение Spell Checker — это проблема и с ней надо бороться (и когда я заглядываю в мониторы коллег и вижу всю эту палитру цветов, я перестаю нормально воспринимать документ :) ).
    P.S. В Excel по дефолту Spell Checker не проводит проверку автоматически. Привыкайте жать F7 перед сохранением.

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

    Поделиться:

    Цитировать

    05.08.2010 в 10:50 # 5762
    Аватар (Belle Morte)
    Belle Morte
    Админ
    Герыч, за быстрое удаление строк из таблицы огромный респект! *THUMBS UP*

    Некоторые полезные приемы работы с офисом есть здесь (спасибо за ссылку Герычу) http://office.microsoft.com/en-us/help/ … 75021.aspx

    Лично мои любимые приемы — format painter (конечно же) и еще изменение размера шрифта по Shift+Ctrl+> и Shift+Ctrl+<

    И еще (об этом наверное почти все знают, но все же) — изменение шрифта на полужирный (ctrl+b), курсив (ctrl+i), подчеркнутый (ctrl+u).

    Поделиться:

    Цитировать

    04.08.2011 в 12:14 # 5763
    Аватар (maglov)
    maglov
    Подписчик

    3. [b]Format Painter.[/b] Убедительно советую — привыкните к этой фиче! Для тех, кто не сталкивался — в 2010 офисе это значок кисточки в правом верхнем углу панели Home (если не ошибаюсь, в 2007 она находится там же). Выделяете абзац, слово, часть таблицы, ячейки (Excel), фигуру/рисунок (особенно удобно в PowerPoint), жмякаете Format Painter и затем просто выделяете то, что вы хотите отформатировать в таком же ключе. Я уже честно говоря отвык использовать стандартные способы форматирования шрифтов, таблиц и т.д. — теперь просто копирую форматирование от абзаца к абзацу.
    P.S. А если кликнуть на Format Painter дважды, можно отформатировать несколько элементов последовательно.

    Ctrl+Shift+C и Ctrl+Shift+V тоже помогают в этом в этом случае.

    Поделиться:

    Цитировать

    16.08.2011 в 21:54 # 5764
    Поздно же я добрался до этой темы… ну да ладно. Вдруг пригодится.

    6. [b]Удаление строк таблицы.[/b] Я долго мучился с удалением строк таблиц в MS Word, пока не нашел быстрое решение — 1) выделяете всю строку (для этого курсор подводите чуть левее самой левой ячейки желаемой строки, пока он не превратиться в стрелку, и кликаете левой кнопкой) и 2) жмякаете Shift + Del.

    Вообще строка таблицы в MS Word прекрасно удаляется нажатием кнопки Backspace после выделения данной строки

    Поделиться:

    Цитировать

    16.08.2011 в 22:10 # 5765
    Да, спасибо, не знал :)
    Тем не менее, выделять всю строку, как описано в п.1, все равно придется. А обычно это и вызывает проблему у многих новичков, ибо просто не знают, что так можно.
    Поделиться:

    Цитировать

    16.08.2011 в 22:18 # 5766
    Согласен
    Поделиться:

    Цитировать

    26.08.2011 в 20:22 # 5767
    Аватар (tilya)
    tilya
    Подписчик
    Мы пишем требования (как собственно и всю другую документацию у нас в компании) в Wiki. На мой взгляд очень удобно, по крайне мере удобней чем в MS Word.

    У нас одна вики-страничка описывает некую функциональность (обычно это некий экран приложения). Страничка содержит название + идентификатор (например, FR-01). Сразу приводится краткое описание функциональности, чтобы читающий понимал, о чем идет речь. Потом идет мокап, далее требования. Каждое требование имеет идентификатор странички + латинскую букву алфавита (например, FR-01-A).

    Страницы все организованы иерархически и слинкованы, где надо. Таким образом, мы можем начать с одной странички с основным экраном (идентификатор, например, FR-01), потом сделать страничку — дочку (идентификатор, например, FR-01-01) и так до бесконечности… :) , можем делать линки на общие требования.

    Мокапы мы рисуем в Balsamiq, у него даже есть плагин под wiki (confluence), так что можно прям из wiki редактировать мокап. Еще не пробывали, т.к. не приобрели пока плагин, но надеюсь скоро попробуем :)

    Поделиться:

    Цитировать

    27.08.2011 в 11:28 # 5768
    Вики — это отличная тема! Я вот как-то лично довольно мало ее использовал, но знаю много примеров удачного использования. Вижу, что есть еще один. Надо будет нам тоже плотнее попробовать ее. Спасибо за то, что пошарил знания!
    Поделиться:

    Цитировать

    27.08.2011 в 22:35 # 5769
    Аватар (MariaM)
    MariaM
    Подписчик

    У нас одна вики-страничка описывает некую функциональность (обычно это некий экран приложения). Страничка содержит название + идентификатор (например, FR-01). Сразу приводится краткое описание функциональности, чтобы читающий понимал, о чем идет речь. Потом идет мокап, далее требования. Каждое требование имеет идентификатор странички + латинскую букву алфавита (например, FR-01-A).

    А можешь скинуть скриншот такой вот вики-странички с примером требования и мокапом. Интересно было бы глянуть образец.

    Мокапы мы рисуем в Balsamiq, у него даже есть плагин под wiki (confluence), так что можно прям из wiki редактировать мокап. Еще не пробывали, т.к. не приобрели пока плагин, но надеюсь скоро попробуем :)

    А у вас Balsamiq на контору куплен или кряк есть? Как вы его вообще добыли и какие от него впечатления?

    Поделиться:

    Цитировать

    29.08.2011 в 07:32 # 5770

    А у вас Balsamiq на контору куплен или кряк есть?

    Сорри, но это оффтоп, ну и плюс такие вопросы на форуме не обсуждаем.

    Поделиться:

    Цитировать

Показано 15 ответов - от 1 до 15 (всего 16)

Вы должны авторизироваться для ответа в этой теме.