iX-Wiki

Das c:\work-Verzeichnis enthält aktuell die Unterverzeichnisse branch, trunk, trunk_minus1, trunk_minus2, trunk_minus3, trunk_minus4 sowie merge-Hilfsverzeichnisse (merge_t_to_b, merge_t1_to_2, merge_t2_to_t1, merge_t3_to_t2 und merge_t4_to_t3). Mit Tortoise SVN werden alle einzeln generierten Datenpakete versioniert gespeichert. Änderungen können somit verfolgt oder auch rückgängig gemacht werden, da der Code zwischen einzelnen Entwicklungsschritten abgeglichen werden kann. Wöchentliche Patches (i. d. R. Bugfixes u. kleinere Anpassungen) werden in den Trunk-Ebenen gespeichert und den Kunden per Update Service zur Verfügung gestellt. Patches werden innerhalb eines Zyklus inkrementell aufgebaut, d. h. das neuere Patch beinhaltet auch alle Inhalte und Verbesserungen seiner Vorgänger. Demgegenüber werden im Branch-Verzeichnis im dreimonatigen Entwicklungszyklus vollständige Updates zu vorhandenen Programmversion entwickelt. Mit diesen so genannten Service Pack werden auch alle Erweiterungen und Korrekturen aus den für die Vorgängerversion generierten Patches zur Verfügung gestellt.

Kundenversionen (Sonderprogrammierungen) werden in Kundenverzeichnissen im Trunk oder Branch separat gespeichert. Sie sind i. A. durch Kopplung an eine Lizenz kundenspezifisch operabel. Andere Varianten für individualisierte Einrichtung sind der Einsatz von speziellen Systemparametern in iX-Haus oder die Einrichtung von Modulen als Zusatzprogramme oder eine Variantensteuerung via Alias-Aufruf. Zum Aufruf solcher Module benötigt man daher dann eine analoge Einrichtung wie beim Kunden und/oder eine adäquate Lizenz.

Als Vorschlag einer entwicklungsinternen Terminologie zur Differenzierung verschiedener kundenspezifischer Modulvarianten im Prozess der Update Notes Erstellung hat die Redaktion folgendes empfohlen:

1. Sonderprogrammierung exklusiv für diesen Kunden: SoPro Kundenname exklusiv

⇒ TR macht nichts weiter.

2. Sonderprogrammierung zunächst nur für diesen Kunden, später für alle: SoPro Kundenname

⇒ TR bereitet Aufnahme in Benutzerdoku vor (zukünftig: legt Eintrag im Wiki an), aber erstellt zunächst keinen Notes Eintrag.

3. Sonderprogrammierung für diesen Kunden geht sofort an alle raus: SoPro Kundenname allgemein

⇒ TR nimmt in Benutzerdoku auf und erstellt den entsprechenden Notes Eintrag.

Updaten der lokalen iX-Haus-Installation des Redakteurs

Wöchentlich wird für Testzwecke im Pfad Q:\RanorexVergleichsdateien\Test-Updates\Branch ein Servicepack aktualisiert zur Verfügung gestellt. Diese Quelle wird als Updatepfad für lokale Testinstanzen auch in der Redaktion genutzt. Am Anfang der Woche kann somit ein Update hierüber abgerufen werden. Darin sind dann alle Anpassungen aus den vorherigen Wochen kumulativ enthalten. Relevant ist dies für Testinstallationen mit dem in Arbeit befindlichen neuen Servicepack.

Zu Beginn der Testphase an einem Monatsende kann dann ein Update über Q:\Deploy\ServicePack\20.17_Next_ServicePack\… genutzt werden.

Das Update der Testversion unter y:\kundenv4\IXODA35 wird i. d. R. durch die CremIT oder ARR vorgenommen. Da es in der internen Dateiverwaltung immer wieder zu Dateisperrkonflikten kommen kann (Benutzer X hat Programm geschlossen, Windowsserver gibt verwendete Programmdatei aber nicht zeitnah frei) ist es sinnvoll, das Update durch die IT vornehmen zu lassen, da diese vorab Dateisperren administrativ aufheben kann.

Für den aktuellen Stand der releasten Version kann der Redakteur eine VM-Ware-Variante auf seinem lokalen PC nutzen. Hier kann ein anstehendes Patch zu Testzwecken eingespielt werden, welches aus Q:\Deploy\… stammt.

In diesem Dokument werden chronologisch fortlaufend je Produktversion kurz und knapp die Änderungen und Korrekturen der wöchentlichen Patches beschrieben. Die kumulierten AddOn-Textdateien im jeweiligen Ordner des Verzeichnisses \\srv-dev\qk\deploy dienen dabei als Quelle. Darin befindet sich alle Texte, welche die Entwickler beim Commit im Bereich Doku zu dem jeweiligen Bug / Erweiterung eingegeben haben. Mit jedem neuen Servicepack startet eine neue Patch-Dokumentation. Derzeit werden Patch Notes für mehrere Versionen erstellt. Die jeweiligen Word Dateien liegen im Doku-Bereich des work-Verzeichnisses auf den Ebenen [Trunk_minus2], [Trunk_minus1] und [Trunk]. Die entsprechenden AddOn Textdateien als Quelle sind zu finden in den deploy-Ebenen [patch_minus2], [patch_minus1] und [patch]. In den Quelldateien, z. B. unter q:\Deploy\Patch_minus2\20.17_Aktuelles_Patch_Minus2\AddOns\update.txt sind die kumulierten Einträge durch Zeitstempel gekennzeichnet. Die wöchentliche Beschreibung beginnt nach dem Zeitstempel, der in der Worddatei unter Datei > Informationen > Eigenschaften im Feld Kommentare eingetragen ist. Bei Abschluss der Beschreibung ist das Kommentare-Feld mit dem letzten Zeitstempel der entsprechenden update.txt zu ergänzen.

Alle AddOn-Einträge, die in der 7er Version enthalten sind, sind auch in der 8er Version enthalten usw. Umgekehrt können ab der 8er Version bei jeder Version spezielle Bugfixes oder Ergänzungen dazugekommen sein. Diese lassen sich in den update.txt-Dateien dadurch identifizieren, dass sie nicht mit (from trunk) gekennzeichnet sind. Sinnvoll ist allerdings in jedem Fall ein Echtzeitabgleich der Versionen auf der Basis dessen, was bereits dokumentiert wurde. Annahmeschluss für Einträge ist i. d. R. freitags 17 Uhr. Wichtig ist nach Erstellung der Inhalte die Aktualisierung des Inhaltsverzeichnisses, sowie unter Datei > Informationen > Eigenschaften > Kommentare die Aktualisierung der Kalenderwoche (Info ist Bestandteil der späteren PDF-Eigenschaften).

Sind die Worddateien comittet, werden automatisch PDFs generiert. Diese sind zu öffnen und auf Korrektheit zu prüfen. Zum Abschluss folgt eine Info-Mail an SMV oder MMV (zur Erzeugung der Update Pakete), dass die Notes online sind.

Vorschläge zur Formulierung der Update Texte in den einzelnen AddOns für die Entwickler:

• Wenn sich die Bearbeitung einer Anpassung oder Erweiterung zeitlich verzögert, sollte ein Hinweis darauf eingefügt werden, so dass die Redaktion notieren kann, dass der entsprechende Update Text bei einem späteren Patch erneut geprüft wird.
• Problem + Lösung kurz notiert
• Zugehöriges Modul nennen

Struktur

Alle Informationen über Änderungen, Erweiterungen und neue Funktionen zum aktuellen Drei-Monatssprint (Service Pack und Patches der Vorversion) sammeln wir in diesem Dokument, das gleichzeitig als Übersicht zu neuen Inhalten der iX-Wiki Benutzerhilfe dient. Das Dokument wird über den Verlauf von vier Service Packs (jeweils Drei-Monatssprints) bis zum Release eines Jahresupdates sukzessive ergänzt und erweitert.

• Wir legen zukünftig zu jedem Versionsrelease eine neue Datei im Ordner Intern der Branchebene an, indem wir die vorherige Releasenotes kopieren und im Dokumentennamen die Version anpassen (19.1, 19.2, 19.3, 20.0). Zur Veröffentlichung des Dokuments legen wir es nach Fertigstellung im allgemeinen Doku-Verzeichnis ab. Dazu muss beim Commit des Dokuments ein RENAME Befehl für jeweils Doc & PDF ausgeführt werden, den smv noch erläutert.
• Inhaltlich wird die vorherige Version um die Inhalte der nächsten Version ergänzt, d. h. die Inhalte z. B. von 19.1, 19.2 und 19.3 werden gemerged und unter dem aktuellen Versionstitel (19.3) zusammengefasst. Dabei strukturieren wir die Inhalte aufgrund der Vielzahl der Neuerungen um und zwar statt als einfache Liste pro Installation wie bisher, zukünftig nach Modulen (Buchhaltung, Stammdaten, usw.) in der Reihenfolge wie im Menübaum in Abschnitten für iX-Haus und in alphabetischer Reihenfolge für iX-Haus plus. [dsn bereitet das vor]
• Erweiterungen aus Patches der Vorversionen bleiben als eigenes Kapitel erhalten, werden jedoch auch über alle Versionen zusammengefasst.
• Zwischenstände werden in der ersten Überschrift gekennzeichnet, z. B. iX-Haus Service Pack 20.19.3 (Zwischenstand 3b)
• Bei den Zwischenständen im Dokument soll evtl. zum Zweck der Testierung als Überschrift „Service Pack“ beibehalten werden statt „Version“. Klärt smv mit HLG ab.
• Die Inhalte der Version 19.0 nehmen wir wieder aus dem Dokument heraus.
• In den Kommentar zum Eintrag schreiben wir die zugehörige AddOn Nummer / Sybille, um bis zum Abschluss der Bearbeitung die Quelle nachzuvollziehen. Weiterhin werden im Kommentar ergänzende Infos, offene Fragen, Bearbeitungszustand etc. benannt. Bei Bedarf senden wir zur fachlichen Korrektur das generierte PDF an Kollegen aus PM / Entwicklung.

Nach redaktioneller Überarbeitung/Kontrolle reduzieren wir den Kommentar auf Neu. Zu Erweiterungen aus Patchnotes enthält der Kommentar die KW der Veröffentlichung.

• In der Bearbeitungsphase der Releasenotes werden zur jeweiligen in Bearbeitung befindlichen Version Zusatzinformationen als ausgeblendeter Text in den Folgeseiten zwischengelagert. Formataufruf mit Strg+d, Alt+a In der Endfassung werden diese Metainformationen entfernt.
• Das Inhaltsverzeichnis ist immer mit ausgeschalteter Darstellung für versteckten Text zu aktualisieren.
• Die Beschreibungen erfolgen vorzugsweise in Aktivform. Sie sind weniger komplex und erleichtern das Leseverständnis. Als Alternative zum Passiv können unpersönliche Pronomen (man, jemand), Infinitiv- (‚sich lassen‘ + Infinitv)‘ oder Adjektivkonstrukte (Adjektiv aus Verb mit Endung ‚-lich‘ oder ‚-bar‘) eingesetzt werden.

Inhalt

Wir suchen gezielt nach Erweiterungen in den AddOns und fügen diese den Releasenotes hinzu. Im Pfad Q:\Deploy\ServicePack\20.17_Next_ServicePack\AddOns wird in der Datei update.txt fortlaufend der Inhalt der update.txt einzelner AddOns kumuliert. Die nicht original aus dem Branch stammenden AddOn-Inhalte enthalten im Titel die Info (from Trunk …). Für solche Erweiterungen nutzen wir den Text aus den Patchnotes. Basiert die Entwicklung auf einem Sybille-Ticket, ist/sind die Sybillenummer/n Bestandteilt des Titels und kann so mit den Vorgaben aus der Sybille abgeglichen werden. In der update.txt der AddOns vermittelt der Entwickler Informationen darüber, ob es eine Doku geben muss und ob diese ggf. als Mini-Doku schon geschrieben/ergänzt wurde. Weiterhin ob z. B. Doku-relevante Zusatzinformationen in dem Sybille-Ticketsystem zu finden sind. Jedes AddOn verweist i. d. R. auf einen Sybille-Eintrag. Dort sind ggf. Pflichten- und Lastenhefte zu finden oder wird die Umsetzung einzelner Features detaillierter diskutiert. Relevant sind daher vor allem die Sybille-Typen Task, Story und Wunsch. Nicht auszuschließen ist jedoch, dass auch Bugfixings zu Erweiterungen führen. Erster Ansprechpartner für alle Erweiterungen ist immer der zugeordnete Produktmanager.

Neben einem kurzgefassten Überblick zur technischen Umsetzung einer Funktion soll in den Release Notes bzw. in der Beschreibung der einzelnen Service Packs insbesondere der Mehrwert / Nutzen neuer Features hervorgehoben werden. Warum wurde diese Neuerung entwickelt, was hat der Anwender davon? Gibt es wichtige ergänzende Hinweise, die hier genannt werden müssen, z. B. wenn sich das Layout oder die Handhabung einer Funktion oder Oberfläche geändert hat. Letztgenannte Infos sind kein Bestandteil des iX-Wiki. Wissen und detaillierte Ausführungen zur Handhabung einer Funktion gehören dagegen in den Text der Onlinehilfe. Bei der Erarbeitung der Notes-Inhalte sollen die Redakteure auch als fachliches Korrektiv für die Texte der Entwickler fungieren. Es ist Ziel, dass die Themen mindestens einem Redakteur verständlich sind und somit in ihrer Aussagekraft für den Anwender möglichst hoch.

Organisation

Im Vorfeld des Sprint Plannings bereiten wir eine Liste der kommenden Features vor, zu denen wir uns dann währenddessen Notizen machen können. Im Anschluss an das Sprint Planning setzt die Redaktion sich zusammen, besprechen grundsätzliche redaktionelle Fragestellungen zu den aktuellen Themen und den konkreten zeitlichen Ablauf für den aktuellen Sprint. Die Erstellung der Release Notes ist untrennbar mit der Erstellung der entsprechenden Inhalte für iX-Wiki verbunden und verläuft zu dieser parallel.

ARR ist derzeit für die inhaltliche Zusammenstellung und fachliche Korrektheit der Release Notes verantwortlich. DSN unterstützt in der Organisation, redigiert in Schleifen die Versionen des Dokumentes und bearbeitet die Inhalte zu iX-Haus plus Themen. Wenn wir auf Themen stoßen, zu denen es noch keine ausreichend aktuellen Hilfeinhalte gibt, nehmen wir diese als ToDos in unsere Übersicht der ToDos Excelliste auf.

Da nach Abschluss der ersten Sprintwoche die ersten Funktionen implementiert sein werden und in der letzten Sprintwoche hauptsächlich getestet und gebugfixt wird, arbeitet ARR idealerweise in der zweiten und dritten Woche eines Monats jeweils dienstags an den Releasenotes und anschließend an der Erstellung der Onlinehilfe-Inhalte. Es gilt das Prinzip first come first serve: alles wird chronologisch abgearbeitet: alle Informationen zu Features der aktuellen Woche werden nacheinander bearbeitet.

Das Produktmanagement erhält mind. 2 Tage vor Sprintende die Releasenotes mit Kommentaren. Abschließende Korrekturen werden daraufhin eingearbeitet und in kommentierter Form intern veröffentlicht (Mail an crem-Gruppe). Eine von Kommentaren und verstecktem Text bereinigte Fassung wird im Allgemein-Verzeichnis des Branch commitet.

Abgleich Sybille <-> AddOns

Der Abgleich von Sybille zu den AddOns und zur Umsetzung in der Doku wird regelmäßig durchgeführt. Basis ist ein aktueller Export aus Sybille gefiltert nach Einträgen mit Bezug auf den jeweiligen Release (Sybillefeld: Servicepack, z. B. 19-3a, 19-3b und 19-3c). Da in Sybille derzeit keine Strukturen für den Dokustatus verfügbar sind, werden die Informationen in einer Exceltabelle mit den Titelinformationen der AddOneinträge der zentralen Datei update.txt aus Q:\Deploy\ServicePack\20.17_Next_ServicePack\AddOns korreliert. Hierzu wird der Inhalt der update.txt-Datei importiert (Mappen ‚Tabelle 1‘ und ‚Tabelle 2‘,) und mit Formeln analysiert (Branch oder Trunk-AddOn, Abgleich mit Sybillenummern über SVERWEIS in Mappe ‚Aufgabe‘). In Tabelle 1 und 2 wird zudem ermittelt, ob sich ein AddOn auf Story oder Task bezieht. Hieraus ergeben sich diverse Status:

• AddOns für den Release geplanter Erweiterungen (nur in Branch)
• AddOns aus einer Trunk-Version und gemerged in Branch (from Trunk)
• AddOns ohne Bezug auf Sybilletickets der aktuellen Releaseversion:
  • sonstige Erweiterungen außerhalb Story/Task (i. d. R. aus Bugfixing)
• Nicht abgeschlossene Story/Tasks mit AddOn:
  • Interimszustand intern (meist bis Testwoche im Status bereit zum Testen)
  • Teilaspekt operabel, Story/Task hiermit aber noch nicht abgeschlossen
• Nicht abgeschlossene Story/Tasks ohne AddOn:
  • noch offene Sybille (neu oder in Bearbeitung durch Entwickler)

Als Zusatzinfo zu dieser Auswertung wird dann der Status der Doku eingetragen. Die Exceldatei liegt auf I:\DOKU und trägt den Release im Namen codiert (z. B. „Aufgaben_2019_3.xlsx“). Dies erlaubt eine relativ zeitnahe Kontrolle z. B. für weitere ToDos in der Doku, insbesondere iX-Wiki-Aktualisierung. Durch Farbcodes kann der Status einer Sybillenummer dargestellt werden. In einfacher Form reicht es aber, eine Liste der relevanten Sybilletickets zu führen und deren Status mit noch nicht angefangen, unfertig (weiß), verschoben (orange) und fertig (grün) zu klassifizieren. In Excel-Kommentar lassen sich dann Zusatzinfos speichern.

Die Basistabelle wird hierzu durch Filterung in Sybille vorbereitet, nach CSV exportiert (frei von Grafiken und Symbolen) dann als Textdatei gewandelt. So kann sie in Excel importiert werden mit einstellbaren Eigenschaften:

• Der Export aus Sybille erzeugt eine Aufgabe.csv-Datei. Diese umbenennen (Datumsstempel und Dateiendung .txt, z. B. „Aufgaben20200624.txt“).
• Excel starten und Datei öffnen (Strg+O), hierbei Dateifilter erweitern auf *.* oder gezielt nach *.txt , …Auswahl… laden
• Excel-Import Schritt 1: Dateityp ⇒ mit getrennten Feldern (Semikolon),
  Dateiursprung: ⇒ 65001 : Unicode (UTF-8), (für korrekte Textformat und Umlaute)
• Excel-Import Schritt 2: Trennzeichen ⇒ Semikolon
• Excel-Import Schritt 3: Datenformat der Spalten einstellen: Standard (oder Text)
• In Excel Spaltenformate anpassen und Inhalte bearbeiten
• Speichern unter (F12) als Dateityp Excel-Arbeitsmappe (.xlsx)

Automatische PDF-Erstellung

Standardmäßig wird bei Committ einer Worddatei die entsprechende PDF-Datei automatisch vom BuildServer erstellt und committet. Sollen Zwischenversionen committet werden (von Worddateien, die noch nicht komplett auslieferungsfertig sind), kann die Erstellung der PDFs mit dem Schalter noDeploy unterbunden werden. Dies ist u. a. wichtig, da Wordkommentare im automatisch generierten PDF erhalten bleiben.

Manuelle PDF-Erstellung

PDFs, die auf Worddokumenten basieren, werden über Word mit der Funktion Speichern unter (F12) erzeugt. Als Dateiformat wird PDF (*.pdf) ausgewählt. Bestimmte Dateieigenschaften werden bei der PDF-Erstellung automatisch übernommen. Hierzu gehört der Dateiname. Dieser wird anhand des Namens der Worddatei vorgeschlagen. Befinden sich im Dateinamen weitere Punkte, kann es je nach Wordversion vorkommen, dass der Dateinamen auf den Textanteil vor dem ersten Punkt reduziert wird, wenn die Optionen aufgerufen werden! In diesem Fall muss der Dateiname nach dem Verlassen der Optionen-Einstellung korrigiert werden. Beispiel: 20.17_ServicePackDoku.docx 20.17_ServicePackDoku  20.pdf  20.17_ServicePackDoku.pdf

Weitere Dateieigenschaften, die in der PDF meistens mit Strg+D abgerufen werden können (Viewer-abhängig) sind: Titel, Verfasser und Stichworte. Daher ist es sinnvoll in Word unter Datei > Eigenschaften die korrespondierenden Felder Titel, Tags und Autor korrekt zu pflegen. Insbesondere über die Tags können hilfreiche Informationen (Keyfacts) transportiert werden.