Организация информационного пространства, Wiki

Цели создания информационного пространства: для чего оно, откуда оно нужно

• Сохранение тайного знания
• Документирование (чем отличается от тайного знания?)
• Brainstorming
• Каталогизация и структуризация

Варианты достижения цели. Почему wiki?

• Бесчисленные бумажки и обрывки
• Складывать в репозиторий
  • То, что нужно, но неудобно - высокий порог вхождения для просмотра и модификации
  • Как узнать, откуда брать репозиторий? — тоже часть информационного пространства
  • Вообще говоря, в инф. пространство входят всякие не связанные непосредственно с кодом вещи — например, у кого просить доступ к тестовым машинам и на каких условиях его дают.
• CMS
• Собственно wiki

Особенности использования wiki

• Связь с багтрекером
  • Достаточно возможности кросслинкинга
• Связь с репозиторием
  • Опять же, ссылки, include.
  • Проблема: иногда хочется страницу из вики в репозитории и документы из репозитория в вики

Требования, предъявляемые к инф. пространству

• Оно должно быть
• У него должен быть низкий порог вхождения

Интеграция wiki и репозитория

• Можно сделать в moin2
  • Рассказать, как это архитектурно устроено.

Вопросы поддержания качества кода

• Что такое есть качество кода?
  • На самом деле, слабоформализуемое понятие.
  • Условно говоря, это совокупность техник написания кода и сопутствующих материалов (некоторые из которых формализуемы, некоторые — нет), минимизирующие накладные расходы на поддержание и дальнейшую разработку
• Среди критериев качества можно отметить:
  • Эффективное выполнение возложенных на ПО задач — самый важный критерий
    • Тестирование
  • Стиль написания кода
    • Формализуемые критерии
      • Форматирование и прочее оформление
    • Неформализуемые критерии
      • Структурирование кода
        • Использование прозрачных алгоритмов при возможности
        • Семантичность именования
  • Документирование
  • Тестирование
• Фактически, в данном случае, задача администратора — как можно более автоматизировать проверку и поддержание соответствия тем составляющим, которые хоть как-то формализутся, и минимизировать ручную работу при проверке/поддержании неформализуемого
  • При этом нужно понимать, что не нужно доводить любую идею, в том 0числе данную, до абсурда и знать меру. Ибо это приводит не к позитивным последствиям, к негативным (разработчики начинают пытаться "обойти систему")
    • В особенности печально пытаться формализовать нечто слабоформализуемое (пример: все имена идентификаторов должны отличаться не менее, чем в двух символах приводит к ii, jj и так далее)
• Про стиль:
  • Два аспекта — отформатировать имеющийся код и помочь писать форматированный новый.
    • Для первого есть всякие штуки типа indent и tidy
    • Для второго — конфигурация любимого редактора
      • Маленький организационный момент: Писать всякое подсказочное в прямо файлы не очень хорошо — мусор, у других людей может быть другой редактор
        • Про другой редактор: в связи с этим во всяких относительно закрытых средах бывает задача разворачивания окружения программиста. Решение, работающее довольно часто — складывать конфигурацию в репо, если форсится ещё и некоторый дистрибутив для разработчиков, то + локальный репозиторий с метапакетом. При желании, настройки тоже можно пакетировать.
        • С одной стороны, сама расставляет отступы и иже, с другой — подсвечивает нарушения стиля. Для vim/pep-8 есть прямо на vim.org (c C сложнее, потому что единого соглашения относительно стиля нет).
• Про комментарии и документирование
  • Вопрос: какая должна быть документация, в каких количествах и видах
    • Комментарии в коде - чтобы понять, что происходит по месту
    • Документация для тех, кто пытается это начать хакать
    • Документация для тех, кто это администрирует/настраивает
    • Документация для тех, кто этим пользуется
    • Для первого пункта очевидно, что это должны быть комментарии по месту, для остальных — ущественно нет.
      • Документация на вики (особенно хорошо в этом плане собственно всяким вики-движкам)
        • Каталог doc/ с документацией в различных форматах
        • Таки да комментарии в коде
    • Вспомнить про XLR!
  • С другой, есть идея, что в качестве комментариев можно сопровождать практически весь объём документации
    • Это позволяет с одной стороны держать всё в одном месте и максимально автоматизировать документирование, с другой — далеко не всегда и не везде удобно (в тому числе, может негативно сказываться а читаемости).
  • С одной стороны, в определённом виде входит в стиль
• Всё неформальное решается посредством review кода
  • Может быть решена совершенно различными способами с разным количеством договорённостей и технологических решений
    • В irc кидать ссылки на пастебины с патчами
    • Рассмотренная ранее схема с взаимодействием посредством почты
    • Всякие навороченные review-тулы в виде вебаппов
  • Задача администратора — сделать так, чтобы оно было удобным
    • Вариант организации с полупубличным репозиторием, в котором постоянный rewrite хистори
    • Почему неудобно в случае патчей вне репозитория (не оформленных как коммитов!) — начинает разъезжаться workflow взаимодействия с обычным репозиторием и с репозиторием с незаапрувленными патчами (для них нужно делать что-то совсем отельное!)
  • Определённый набор средств предоставляют сами VCS — рассматриваемый ранее workflow с почтой
  • Из готовых решений — reviewboard, с рюшечками и прочим.

Ссылки

• Moin: http://master19.moinmo.in/ПомощьПоГлавам

• Moin2: http://moinmo.in/MoinMoin2.0#Storage_API

• Лекция про style guide

• Лекция про документирование