Написание руководства для всей компании


17

Я работаю в небольшой компании. Отдел разработки программного обеспечения компании до того, как меня наняли, состоял из одного перегруженного самоучкой парня. Теперь, когда я несколько лет писал программное обеспечение для компании, мне было поручено установить официальные методы разработки программного обеспечения в масштабах всей компании. В настоящее время у нас нет руководящих принципов, кроме

Напишите код, протестируйте его, поместите в файл .zip и отправьте клиенту. Бонусные баллы за TDD и контроль версий.

Мой начальник хочет, чтобы я написал руководство для разработчика программного обеспечения, в котором определены общие процессы, протоколы, инструменты и рекомендации, которые мы используем для достижения цели. Другими словами, он хочет, чтобы книга «Это то, что мы делаем здесь», чтобы было проще познакомить нового сотрудника с тем, как мы делаем вещи, а также чтобы помочь моему боссу понять, что делают его миньоны и как они это делают. Это.

То, как я это вижу, я закладываю фундамент, и это нужно сделать правильно. Как бы вы выбрали темы для такого справочника? Можете ли вы привести несколько примеров тем?

Примечание: если это имеет значение, мы, прежде всего, магазин Microsoft .NET. И мы смотрим на гибкие практики, такие как XP и Scrum, но нам, возможно, придется серьезно изменить их, чтобы они работали в нашей компании.


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

покупки для справочных тем?
комнат

1
@gnat Хорошая мысль. Смотрите редактировать.
Фил

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

1
Меня не очень интересует, как оценить важность тем, так как я думаю, что уже могу это сделать. Скорее я ищу примеры. Я всегда считал ответы на абстрактные вопросы лучше, когда их сопровождали примерами. Смотрите редактировать. Кстати, я ценю вашу помощь, чтобы сделать мой вопрос лучше.
Фил

Ответы:


20

Я бы разбил его на разделы, такие как

  • Текущий штат - имена и должности (в идеале с фотографиями)
  • Заявки, логины к ним, данные, которые нужно знать, и запросы на разрешение, которые были отправлены
  • Закладки на сайтах компании и ключевых внешних сайтах, имеющих отношение к бизнесу
  • Приложения, которые компания использует для связи, электронной почты, бронирования конференц-зала, sharecreen
  • Процедуры для связанных с компанией действий, таких как Расходные квитанции, бронирование поездки
  • Настройка машины разработчика. Подробно опишите процесс настройки новой машины для разработчиков. Обычно это «ожидается», чтобы занять всего один день, но на самом деле это обычно занимает 3-5 дней.
  • Процесс разработки, как работа отслеживается, назначается и обновляется и какие инструменты используются.
  • Как проверить, что проверить, когда проверить, где проверить.
  • Стандарты кодирования, включая соглашения об именах файлов и стандарты для конкретных языков.
  • Как обрабатывать ошибки, где их документировать, как их исправлять.
  • Процесс развертывания, каковы основные вещи, которые нужно знать для производства.
  • Как документировать, что документировать, когда документировать.
  • Где материал «есть», например, местоположение (я) для кода, данных, стандартов, документации, ссылок и других активов.

Модульность также позволит вам или другим людям обновлять отдельные элементы по отдельности, например, имена и должности сотрудников будут часто меняться по мере прихода и ухода людей.

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

Для Agile / SCRUM:

Самая сложная часть работы с Agile и SCRUM - это «действительно».

Для чтения я бы начал с http://agilemanifesto.org/ и пошел оттуда.

Я также прочитал бы известный http://www.halfarsedagilemanifesto.org/, который добавляет вес к факту, что вам действительно нужно принять все аспекты, чтобы это работало. Если вам придется сильно модифицировать Agile для своих организаций, вполне вероятно, что люди хотят получить выгоды - без использования правильных процессов. Этот факт сам по себе должен быть представлен, чтобы отразить любую полусмысленность.


6
Мне нравится, как часто вы редактируете это. Как ... ловко с вашей стороны. :)
Фил

Мы не обязательно хотим изменить гибкие принципы в целом. Мы просто изменили бы определенные практики, такие как XP, так как у нас не было бы рабочей силы для реализации всех необходимых ролей. Это может быть другой вопрос для другого дня.
Фил

Извините, я удалил ответ на данный момент, потому что вопрос был изменен.
Фил

1
Бонусные баллы, если вы создадите вики компании для хранения этой информации ...
Спенсер Рэтбун,

Привет, Спенсер, это интересно. Я также только начал использовать github wiki с уценкой. Любые мысли о том, как они сравниваются. Очевидно, что многие люди знают github по коду и по уценке из SO, поэтому его легко принять.
Майкл Даррант

4

Похоже, вам придется ввести некоторые практики, прежде чем документировать их!

а) Контроль источников - как вы храните свои источники и делаете контроль версий

б) Управление выпуском и отслеживание - как вы делаете сборку, нумеруете релиз, сравниваете текущий релиз-кандидат с предыдущим выпуском

c) Управление проблемами - как вы отслеживаете ошибки в своих выпусках.

Это довольно простые вещи, но их реализация может занять много времени (и, возможно, стоить денег).


2
+1 за простоту и сосредоточенность на важных вопросах. Нам действительно не нужны мандаты "большого правительства" на стили кодирования.
kirk.burleson

3

Темы, которые я бы включил в справочник разработчика:

  • Роли / должности в отделе и их соответствующие обязанности
  • Требования к программному обеспечению компьютера разработчика (т.е. необходимая среда разработки)
  • Где и как получить доступ к хранилищу исходного кода
  • Используемые инструменты разработки (например, IDE)
  • Стиль кодирования / стандарты
  • Стандарты документации
  • Процесс тестирования
  • Процесс сборки
  • Процесс развертывания
  • Поддержка и процесс управления проблемами
  • Где взять самую последнюю версию этого руководства

Имейте в виду, что это руководство должно содержать только элементы, относящиеся к разработке, а не информацию всей компании (которая должна быть в руководстве для сотрудников).


2

Использование контроля источника

  • Какой инструмент управления исходным кодом вы используете.
  • Синтаксис общих команд / инструментов в IDE.
  • Стратегия ветвления / слияния.
  • Какой должна быть единица коммита? Как долго это слишком долго, чтобы файл был извлечен / не зафиксирован?
  • Какой уровень «донесенности» обозначает фиксация / регистрация? Собирает? Юнит тесты проходят? Отзыв?
  • Что ожидается включить в заметки для фиксации / регистрации.
  • Процедуры отката.
Используя наш сайт, вы подтверждаете, что прочитали и поняли нашу Политику в отношении файлов cookie и Политику конфиденциальности.
Licensed under cc by-sa 3.0 with attribution required.