Pisanie podręcznika programisty dla całej firmy

17

Pracuję dla małej firmy. Dział rozwoju oprogramowania firmy, zanim zostałem zatrudniony, składał się z jednego samouka, przepracowanego faceta. Teraz, gdy piszę oprogramowanie dla firmy od kilku lat, mam za zadanie ustanowienie formalnych praktyk rozwoju oprogramowania w całej firmie. Obecnie nie mamy żadnych innych wytycznych niż

Napisz kod, przetestuj go, umieść w pliku .zip i wyślij do klienta. Punkty bonusowe za TDD i kontrolę wersji.

Mój szef chce, żebym napisał podręcznik dla programistów, który określa ogólne procesy, protokoły, narzędzia i wytyczne, których używamy do wykonywania zadań. Innymi słowy, chce książki „Oto, co tu robimy”, aby ułatwić nowemu pracownikowi zapoznanie się ze sposobem, w jaki robimy rzeczy, a także by pomóc mojemu szefowi zrozumieć, co robią jego podwładni i jak się zachowują to.

Z mojego punktu widzenia kładę podwaliny i trzeba to zrobić dobrze. Jak zabrałbyś się do wybierania tematów do takiego podręcznika? Czy możesz podać jakieś przykładowe tematy?

Uwaga boczna: jeśli to ważne, jesteśmy przede wszystkim sklepem Microsoft .NET. Patrzymy na zwinne praktyki, takie jak XP i Scrum, ale być może będziemy musieli je poważnie zmodyfikować, aby działały w naszej firmie.

Phil
źródło
3
Twój obecny proces jest bardzo słaby. Czy masz wsparcie firmy w zakresie zmiany obecnego procesu, nie będzie on tani, wymagany rodzaj zmiany wymaga pieniędzy. Istnieje wiele książek na ten temat, większość tych praktyk ma narzędzia, które należy wdrożyć w taki sposób, aby nie wymagały dużego wysiłku.
Ramhound
robisz zakupy na tematy podręczników?
komar
1
@gnat Dobra uwaga. Zobacz edycję.
Phil
dobra edycja (podobno podążałeś za linkiem). Chciałbym również zmienić Jakie rodzaje tematów uważasz za ważne ... na coś w rodzaju Jak oceniłbyś ważność tematów ... - w ten sposób byłoby bardziej zgodne z wytycznymi Jeffa, o ile rozumiem
komar
1
Naprawdę nie martwię się, jak ocenić ważność tematów, ponieważ myślę, że już mogę to zrobić. Zamiast tego szukam przykładów. Zawsze uważałem, że odpowiedzi na pytania abstrakcyjne są lepsze, jeśli towarzyszą im przykłady. Zobacz edycję. BTW, doceniam twoją pomoc w ulepszeniu mojego pytania.
Phil

Odpowiedzi:

20

Podzielę to na części takie jak

  • Obecni pracownicy - nazwiska i tytuły (najlepiej ze zdjęciami)
  • Wnioski, loginy do nich, dane do poznania i wnioski o pozwolenie na przesłanie
  • Zakładki do witryn firmowych i kluczowych witryn zewnętrznych istotnych dla firmy
  • Aplikacje używane przez firmę do komunikacji, poczty e-mail, rezerwacji sal konferencyjnych, udostępniania ekranu
  • Procedury dotyczące działań związanych z firmą, takich jak wydawanie rachunków, rezerwacja podróży
  • Konfiguracja maszyny programisty. Szczegółowo opisz proces konfigurowania nowego komputera dla programistów. Zazwyczaj „oczekuje się”, że zajmie to tylko jeden dzień, ale w rzeczywistości często zajmuje 3-5 dni.
  • Proces opracowywania, sposób śledzenia, przydzielania i aktualizowania pracy oraz stosowane narzędzia.
  • Jak testować, co testować, kiedy testować, gdzie testować.
  • Standardy kodowania, w tym konwencje nazewnictwa plików i standardy specyficzne dla języka.
  • Jak radzić sobie z błędami, gdzie je dokumentować, jak je naprawić.
  • proces wdrażania, jakie są kluczowe rzeczy do wypchnięcia produkcji.
  • Jak dokumentować, co dokumentować, kiedy dokumentować.
  • Gdzie rzeczy „są”, np. Lokalizacja (y) dla kodu, danych, standardów, dokumentacji, łączy i innych zasobów.

Dzięki modułowej konfiguracji Ty i inni możecie osobno aktualizować elementy osobno, na przykład nazwiska i stanowiska pracowników będą się często zmieniać, gdy ludzie przychodzą i odchodzą.

Dla każdej sekcji postaram się napisać ją z punktu widzenia „początkującego”. Najważniejsze będzie upewnienie się, że to naprawdę ma sens dla początkującego. Twój szef oczywiście nie jest właściwą osobą do przeglądu tego, ponieważ nie jest on zamierzoną publicznością. Ma prawo tego chcieć, po prostu upewnij się, że treść nie zostanie przez niego przetestowana . Także „nowicjusz” oboje mają „1 tydzień” jako nowicjusz… i ma tylko jeden punkt widzenia. Jest więc prawdopodobne (i zalecane), że dokument zostanie dopracowany przy każdym nowym pracowniku. W rzeczywistości całkiem dobrym zadaniem jest przypisanie ich również na pierwszy tydzień, tj. „Zaktualizuj podręcznik dla początkujących”.

Dla Agile / SCRUM:

Najtrudniejszą częścią robienia Agile i SCRUM jest „naprawdę” robienie tego.

Do czytania zacznę od http://agilemanifesto.org/ i zacznę od tego miejsca.

Przeczytałbym również dobrze znany http://www.halfarsedagilemanifesto.org/, który dodaje wagi temu, że naprawdę musisz uwzględnić wszystkie aspekty, aby to zadziałało. Jeśli musisz mocno zmodyfikować Agile w swoich organizacjach, prawdopodobnie ludzie będą chcieli uzyskać korzyści - bez korzystania z odpowiednich procesów. Sam fakt ten powinien zostać przedstawiony, aby odeprzeć jakąkolwiek półpoważność.

Michael Durrant
źródło
6
Podoba mi się, jak często to edytujesz. Jak ... zwinny z ciebie. :)
Phil
Niekoniecznie chcemy modyfikować zasady zwinności w ogóle. Po prostu zmodyfikowalibyśmy określone praktyki, takie jak XP, ponieważ tak naprawdę nie mamy siły roboczej do wdrożenia wszystkich wymaganych ról. To może być kolejne pytanie na inny dzień.
Phil
Niestety, na razie usunąłem odpowiedź, ponieważ pytanie zostało zmodyfikowane.
Phil
1
Punkty bonusowe, jeśli założysz wiki firmowe do przechowywania tych informacji ...
Spencer Rathbun
Cześć Spencer, to interesujące. Zacząłem też używać wiki github z markdown. Wszelkie przemyślenia na temat ich porównania. Oczywiście wielu ludzi zna github z kodu i obniżkę z SO, więc łatwo jest je adoptować.
Michael Durrant
4

Wygląda na to, że będziesz musiał wprowadzić pewne praktyki, zanim je udokumentujesz!

a) Kontrola źródła - w jaki sposób przechowujesz źródła i kontrolujesz zmiany

b) Zarządzanie wersjami i ich monitorowanie - w jaki sposób wykonujesz kompilację, numerujesz wersję, porównujesz aktualnego kandydata do poprzedniej wersji

c) Zarządzanie problemami - jak śledzić błędy w swoich wydaniach.

Są to dość podstawowe rzeczy, ale ich wdrożenie może zająć dużo czasu (i być może kosztować).

Scott C. Wilson
źródło
2
+1 za uproszczenie i skoncentrowanie się na ważnych kwestiach. Naprawdę nie potrzebujemy mandatów „wielkiego rządu” w zakresie stylów kodowania.
kirk.burleson
3

Tematy, które chciałbym zawrzeć w podręczniku programisty:

  • Role / stanowiska w dziale i odpowiadające im obowiązki
  • Wymagania dotyczące oprogramowania dla programistów (tj. Wymagane środowisko programistyczne)
  • Gdzie i jak uzyskać dostęp do repozytorium kodu źródłowego
  • Używane narzędzia programistyczne (np. IDE)
  • Styl / standardy kodowania
  • Standardy dokumentacji
  • Proces testowania
  • Zbuduj proces
  • Proces wdrażania
  • Proces wsparcia i zarządzania problemami
  • Gdzie znaleźć najnowszą wersję tego podręcznika

Należy pamiętać, że ten podręcznik powinien zawierać wyłącznie elementy specyficzne dla rozwoju, a nie informacje dotyczące całej firmy (które powinny znajdować się w podręczniku dla pracowników).

Bernard
źródło
2

Korzystanie z kontroli źródła

  • Z jakiego narzędzia kontroli źródła korzystasz.
  • Składnia typowych poleceń / narzędzi w IDE.
  • Strategia rozgałęziania / łączenia.
  • Jaka powinna być jednostka zatwierdzenia? Jak długo jest za długi, aby plik został wyewidencjonowany / nie został zatwierdzony?
  • Jaki poziom „charytatywności” oznacza zatwierdzenie / odprawa? Kompiluje? Czy testy jednostkowe przebiegły pomyślnie? Oceniony?
  • Czego należy się spodziewać w uwagach dotyczących zatwierdzenia / odprawy.
  • Procedury wycofywania.
JohnMcG
źródło