iX-Wiki

Allgemein

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.

Automatische PDF-Erstellung aus Worddateien über BuildServer

Ab 12.02.2019 wurde der BuildServer um eine AutoCommitPDF-Funktionalität erweitert. Immer wenn eine Worddatei committet wird, wird 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.

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)