Documentation Driven Development in Magento?

Ich gebe zu, der Titel ist ein bisschen reißerisch. Generell haben wir öfter das Problem dass wir gemeinsam am Projekt arbeiten, alles fleißig notieren und konzipieren und es dann umsetzen. Viel zu oft verschwinden die Konzepte dann im Papierkorb bzw. laufen immer weiter zum Entwicklungsstand auseinander. Will man wissen wie etwas noch mal ging tut man was? Genau, man ließt den Source. Da sich das ganze irgendwie umständlich anfühlt haben wir ein recht simples Magento Modul mit dem Namen Docview entwickelt. Eventuell löst es unser Problem?

Mit DocView wird Dokumentation der Module an einer zentralen Stelle gesammelt und in Magento angezeigt. Damit ein Modul Doku bereitstellt muss eine index.md angelegt sein. Diese liegt z.B. im Ordner app/code/local/code/Codex/MeinModul/doc/index.md.

menu

Beim Aufruf der Doku geht Docview nun her und sammelt alle index.md aller Magento Module ein, verwandelt sie in HTML und stellt sie untereinander da. Eine Index.md sollte also immer ein paar kurze Erklärungen und weiterführende Links, wiederrum auf weitere Markdown-Dokumente, enthalten. So findet man im Idealfall was man sucht ohne direkt erschlagen zu werden.

Generell unterscheidet Docview übrigens in Kunden-Doku (wie stoße ich noch mal Prozess xyz an?) und Entwickler-Doku (Woher bekommt der Import seine Daten und wie oft?). Kunden-Doku liegt als index.md im doc/-Ordner, Doku für Entwickler unter doc/dev/index.md. Alles ganz simpel als Markdown-Datei.

docview-650x444

Entwicklungsprozess

Da nun das Konzept, die Anleitung zur Bedienung usw. zu dem Modul direkt im Git-Repo liegt und ein einfaches Markdown Dokument ist kann jeder es beim programmieren direkt erweitern. Man muss nicht erst in ein anderes Portal springen, das Modul-Suchen, die Version und dort etwas ändern. Das war nämlich vom Prozess einfach so komplex dass es am Ende niemand tat und die Doku schnell "outdated" war.  Gleichzeitig passt die Doku direkt zum Versionsstand der dort eingesetzt ist. Geht ein neues Feature live bzw. wird "gemerded" ändert sich auch die aktuelle Doku mit Master-Branch direkt mit.

Ich für meinen Teil überführe die Konzepte - die wir zumindest grob vor der Programmierung ohne haben - nun vorher in ein Markdown-Dokument bzw. erstellte sie direkt dort. Danach programmiere ich dann auf die üblichen Wege mein Modul - aber diesmal weiß ich wo ich in 8 Wochen finde was es tut. Nämlich im Magento Admin - für alle direkt sichtbar und transparent.

entwickler

 

Natürlich ist der aktuelle Entwicklungsstand auf Github zu finden :-)



Ein Beitrag von Tobias Vogt
Tobias's avatar

Tobias Vogt arbeitet seit 2008 mit Magento und ist seit 2011 durch Magento zertifizierter Entwickler. Beschäftigt ist er bei der code-x GmbH, einer Agentur für Internet und Marketing aus Paderborn. Er gehört zum Gründer-Team der Webguys und ist seit November 2011 Bachelor of Science (Wirtschaftsinformatik). Sie erreichen Ihn per E-Mail unter tobi@webguys.de.

Alle Beiträge von Tobias

Kommentare
Magento-Neuigkeiten #42 am

[…] Witzigerweise schrieb Tobi zur gleichen Zeit eine ganz ähnliche Extension: Codex_Docview. […]

TWiST #64: Galeria Kaufhof setzt auf Eigenentwicklung, Intershop-Finanzvorstand wirft das Handtuch | ShopTechBlog am

[…] Documentation Driven Development in Magento? […]

Dein Kommentar