A shiny User Guide from your Code Repo

When you start thinking about a user guide for your shiny new software product you have to think about

  1. who will be reading it -> make a list of end users
  2. where you put it -> it has to be available for all the end users, but also practical for you to work on without changing your whole environment.

Mostly the users of a product are using other tools then the common software developer. They like to read a user guide in their Business Wiki or in a nice formatted PDF or on a shiny web site, which they can reach directly from the product.

As a developer I don´t want to think about formatting and designing a nice document. I want to add my content to a file, start an automation and magically get a readable document that fulfills all those requirements.

Therefore the content of the user guide should be managed in your code repository next to your other work. Markdown files are most suitable for this, because they include the plain text and can be used easily with other tools which do all the magic. You can add one file for each chapter to make it easy to work on each chapter independently, with different people, make reviews and keep them versioned in git.

Add repo in Git and add your markdown files

Add a git repository for your user guide and add some markdown files for the chapters you want to include. The following chapters are examples for chapters commonly used in a user guide:

  1. Introduction
  2. Feature Overview
  3. Getting started
  4. User interface (step-by-step instructions)
  5. Advanced Features
  6. Main Use Cases (Best practices)
  7. Maintenance
  8. Troubleshooting
  9. Frequently asked questions
  10. Glossary
  11. Contact information

But of course you can change these to your needs.

Add a readme file with a short introduction about your product, a table of contents and instructions on how to build the user guide to the different output formats that you need.

Install Pandoc and Latex on your local machine

The generation of nice PDFs and a HTML page can be done with Pandoc and Latex. Those tools have to be installed on your local machine.

Add configuration and template files

In the folder „manual“ you can find your markdown files, a make file which makes the magical generation with Pandoc, some metadata, to configure for example the title, author, date, version, logo etc. and a folder for the images you want to include in your user guide.

The content of the Makefile only defines the tool directory and calls the second make file:

export TOOL_DIR = tool
include $(TOOL_DIR)/Makefile_include

The metadata.yml file defines your parameters for the user guide:

---
title: "Template Device"
title-prefix: "User Manual"
subtitle: "User Manual"
author: [xxx xxxx]
date: "2024-03-01" ## you can also add \today to have the current date after every build
subject: "Markdown"
keywords: [Markdown, Example]
lang: "en"
titlepage: true
titlepage-text-color: "005e85"
titlepage-rule-color: "005e85"
titlepage-rule-height: 2
logo: "images/libresolar-logo-lateral.pdf"
logo-width: 200
toc-own-page: true
...

The tool folder

Then you have the folder called „tool„, which includes the templates and another make-file, which will be called from the first one .

The second make file defines the make functions which will be called from your terminal to generate the PDF or HTML or both and add them to the build folder.

# NOTE This variable has to be defined in the including file:
#TOOL_DIR = tool

OUT_DIR = build
RESOURCES = $(TOOL_DIR)/template images
MKDIR_P = mkdir -p

# Targets not producing a file with their name
.PHONY: all pdf html dist clean

all:: pdf html

# Creates the PDF from your markdown files with the eisvogel template
pdf:: metadata.yml *.md
	pandoc \
		metadata.yml *.md \
		--output manual.pdf \
		--template $(TOOL_DIR)/template/eisvogel.tex \
		--from markdown \
		--listings \
		--number-sections \
		--table-of-contents \
		--metadata date="`date -u '+%Y-%m-%d'`" #You can change the date format here

# Creates the HTML page from your markdown files with the mdbook template
html:: metadata.yml *.md
	pandoc \
		metadata.yml *.md \
		--output manual.html \
		--template $(TOOL_DIR)/template/mdbook.html \
		--from markdown \
		--listings \
		--number-sections \
		--table-of-contents \
		--toc-depth=2 \
		--katex \
		--metadata date="`date -u '+%Y-%m-%d'`" #You can change the date format here

# Creates a new directory for the distribution named build, copys the pdf and html into it and also the images and template directory. You can also manually add a build directory in your repo and remove the command to add a new directory here.
dist:: all
	${MKDIR_P} ${OUT_DIR}
	cp -r ${RESOURCES} ${OUT_DIR}/
	mv manual.pdf ${OUT_DIR}/
	mv manual.html ${OUT_DIR}/index.html

# Deletes the PDF and HMTL file and the build directory from the first level
clean::
	rm -f manual.pdf
	rm -f manual.html
	rm -rf ${OUT_DIR}

The template folder

In the „template“ folder you find the latex „Eisvogel“ template for the PDF and the template files for the HTML page, including the mdbook-Template, CSS-files, some Javascript, fonts etc.

The build folder

The „build“ folder will include the final PDF and HTML page to be deployed whereever you want to have it. This folder can also be pushed somewhere during the deployment process and is then included into your continuous integration process.

Link to download the template

In the following Github project a template for this solution can be downloaded and used in your repo: https://github.com/LibreSolar/md-manual-template/

Intuitive und kostenlose iTunes Alternative für Musik und Videos

Wie oft habe ich mich schon mit diesem Apple-Programm rumgeärgert und es bis heute nicht verstanden.. wo doch Apple immer so intuitiv zu bedienen sein soll. ITunes ist für mich noch nie intuitiv gewesen, sondern eher ein Alptraum, der gern auch mal einfach alles vom iPhone löscht, weil man vergessen hat, daß man die Synchronisieren-Funktion nicht einfach auf einem anderen Rechner benutzen kann, weil dann alles mit den dort nicht vorhandenen Ordnern überschrieben wird. Und auch der Wechsel zwischen den Tabs und die Menüführung will sich mir einfach nicht erschließen.

itunes1

Vor einiger Zeit habe ich aber ein Programm gefunden, das zumindest für Musik eine kostenlose und wirklich einfach und intuitiv zu bedienende Alternative darstellt. Ich teste das jetzt schon seit mehreren Monaten von diversen Rechnern und Geräten und bin immer noch glücklich damit, daher sei es hier ausdrücklich empfohlen für alle die einfach nur Musik auf ihre I-Geräte kopieren und dort verwalten möchten. Das Programm gibt es auch für Fotos, Kontakte und Apps oder als Backuplösung, aber diese Anwendungen muss man dann bezahlen, daher hab ichs bisher noch nicht getestet. Vielleicht mach ich das aber auch bald, habe gerade mal wieder ausversehen sämtliche Bilder von meinem IPhone gelöscht 🙂

Weiterlesen

Ein Docker-Container – und Deine Anwendung läuft überall

„But it works on my machine!“

Diese allseits bekannte Entwickler-Wahrheit deutet schon seit langem darauf hin, daß die Portierung einer perfekt funktionierenden Anwendung in einen anderen Kontext immer schwieriger wird. Immer mehr Tools, Konfigurationen und unvorhergesehene Sicherheitsbestimmungen.. da kann die Präsentation der schönsten Anwendung zum frustrierenden Erlebnis werden.

dockerlogo

Transport im Docker-Container

Die Macher von Docker haben sich gedacht, daß es ja wohl nicht sein kann, daß die Menschheit mittlerweile Waren in jeglicher Form an jeglichen Ort der Welt verschiffen kann, aber die IT-Welt es immer noch nicht hinkriegt, problemlos eine Anwendung von einem Kontext in den nächsten zu portieren. In Anlehnung an diese Allegorie wurde 2013 der Docker-Container erfunden. Ebenso wie ein großer Schiffscontainer ein einheitliches (seit 1956 nach ISO-Norm standardisiertes) Format hat, das gleichermaßen von Schiffen und LKWs transportiert und gestapelt werden kann und mit beliebigem Inhalt zu befüllen ist, ist der Docker-Container dafür zuständig, eine Anwendung beliebiger Art so in sich zu kapseln, daß der Container alle Kontextinformationen übernimmt und sich problemlos in verschiedene Umgebungen verschieben lässt.

docker-containers

Quelle: Eine Folie des Docker Erfinders Solomon Hykes aus seiner Präsentation während der DockerCon Konferenz im Juni 2014.

Weiterlesen

Erstellen einer TimeSlider Animation mit GWT

In meiner letzten GWT-Webanwendung ging es unter anderem um die Animation von grafischen Elementen. Zum Beispiel sollten U-Bahnen in einem U-Bahnnetz dargestellt werden und der Nutzer sollte die Animation für einen selbstgewählten Zeitraum abspielen können. So sollten z.B. alle U-Bahnen, die zwischen 6 Uhr und 10 Uhr morgens eine bestimmte Station passieren, animiert werden. Diese Animationen habe ich mit JavaScript gebaut. Die Steuerung der Animationen wollte ich jedoch mit GWT-Elementen in die Anwendung einbauen. Dazu brauchte ich Buttons zum Starten und Stoppen der Animation, sowie eine Zeitanzeige, die den Fortschritt der Animation darstellt. Ich war mir ziemlich sicher, daß dies eine Standardfunktion ist, für die es passende Bibliotheken gibt.

Vorhandene Bibliotheken für einen GWT-Slider

Nach langwierigen Recherchen für diesen Anwendungsfall bin ich jedoch nicht fündig geworden. GWT bietet von sich aus keine fertigen Slideranimationen an. Es gibt zwar eine SliderBar im Inkubator, aber diese ist bisher nicht in die offizielle Bibliothek aufgenommen worden.

Ausprobiert habe ich unter anderem die gwt-slider-bar-Bibliothek.  Dies ging zwar in die richtige Richtung, aber der Overhead zum Installieren und Benutzen der Bibliothek war relativ groß und die grafische Umsetzung gefiel mir auch nicht besonders. Diese ist zwar komplett in CSS konfigurierbar, aber dann ist der Nutzen der Bibliothek insgesamt relativ gering. Ein Entwickler von devbliss bietet übrigens einen Cleanup dieser Bibliothek an, mit einer Mavenintegration und besserer Usability der CSS-Styles.

gwt-slider-bar

Schöne Slider gibt es von JQuery oder anderen JavaScript-Bibliotheken. Eine gute Lösung zur Einbindung eines JQuery-Sliders in GWT wird hier vorgestellt.

jquery-slider

Aber moment mal: ich wollte doch eigentlich in GWT mit Java programmieren! Die Integration von JavaScript in GWT ist immer etwas umständlich und man muss die JSNI-Methoden verwenden. Ich kam also zu dem Schluss, dass es einfacher ist, einen eigenen Slider mit den vorhandenen GWT-Elementen zu bauen. Da dies einwandfrei und relativ flott funktioniert hat, möchte ich euch diese Variante hier vorstellen.

 Grafische Elemente des TigerTech TimeSliders

Ein Slider besteht aus den folgenden Elementen: einem Hauptpanel, in welchem sich der Slider bewegt, einem SliderHandle, der von links nach rechts wandert und jeweils einem Panel auf der linken sowie der rechten Seite des SliderHandles, deren Größe sich während der Animation ändert.

slider-sketch

Weiterlesen

Entscheidung für ein passendes Web Application Framework

Du hast eine spitzen Idee für eine Web-Anwendung und willst am liebsten gleich losprogrammieren. Aber beim Einrichten Deiner Entwicklungsumgebung fällt Dir ein, daß du gerne mal etwas Neues ausprobieren möchtest, das Dir ein paar Arbeitsschritte erspart und ein schickes modernes Design liefert. Du möchtest gerne ein Web-Application-Framework verwenden.

Ein Web Application Framework ist grundsätzlich für die Entwicklung von dynamischen Webseiten, Webanwendungen oder Webservices ausgelegt. Damit werden sich wiederholende Tätigkeiten vereinfacht, die Wiederverwendung von Code und die Selbstdokumentation der Software-Entwicklung gefördert. Begibt man sich allerdings auf die Suche stellt man schnell fest, daß es unendlich viele Möglichkeiten gibt. Deshalb sollte man zunächst festlegen, welche Anforderungen man an ein solches Framework hat und dann die Alternativen nach diesen Anforderungen hin abklopfen.  Die Frage nach richtig oder falsch läßt sich natürlich so einfach nicht beantworten, aber gut ist es doch ein paar Vor- und Nachteile zu kennen.

web-frameworks

Weiterlesen

Datenbanken für Couch Potatoes und Big Data Management

No more SQL?

Viele Entwickler verwenden heute Datenbanken, die ohne oder mit wenig SQL auskommen. Ein Trend der sich NoSQL nennt.

Der Begriff NoSQL wird zunächst durch das defniert was er nicht ist, nämlich kein SQL. Er wurde erstmalig 2009 von Eric Evans für ein Event in San Francisco verwendet. Vorrangig sollte er als provokative Phrase aufgefasst werden, als Abgrenzung zu der strukturierten Abfragesprache SQL. NoSQL hat zum Ziel, Alternativen zum allgegenwärtigen relationalen Datenbankmodell und üblichen Datenbanktechnologien aufzuzeigen, die für bestimmte Anwendungsfälle besser geeignet sind. Mit dem Web2.0 und dem damit einhergehenden Bedarf nach der Verarbeitung großer Datenmengen erfuhren NoSQL-Datenbanken ein sehr schnelles Wachstum. Die Vereinigung fast aller nicht relationaler Datenbanken unter dem Begriff NoSQL zeigte eine ernstzunehmende Alternative zu SQL-Datenbanken auf. Mittlerweile wird der Begriff von großen Teilen der Community als „Not-only-SQL“ aufgefasst, um somit die strikte Abgrenzung wieder aufzuweichen. Es gibt auch viele Hybrid-Lösungen. Je nach Anwendung gilt es die richtige Datenbank auszuwählen und in vielen (vor allem sicherheitskritischen und komplexen) Fällen ist eine relationale Datenbank auch nach wie vor die richtige Lösung. Die NoSQL-Bewegung setzt sich grundsätzlich für eine freie Datenbankauswahl ein und schärft das Bewußtsein für das große Spektrum an Datenbanken, das zur Verfügung steht.

Im NoSQL-Archiv von Dr. Prof. Stefan Edlich sind alle NoSQL-Datenbanken aufgeführt, aktuell bereits 150!

sql-vs-nosql

Weiterlesen

„Git“ your work done and don´t mess with your team!

Verteilte Versionsverwaltung mit GIT

Wichtigstes Tool für die Softwareentwicklung im Team ist eine funktionierende Versionsverwaltung. Nach den zentralisierten Systemen CVS, Subversion und anderen, ist aktuell das verteilte System Git das Tool der Wahl mit coolen neuen Features. Es ist besonders gut geeignet für große, verteilte OpenSource-Projekte, um viel Diskussion um Commit-Zugänge zu vermeiden und es jedem Entwickler einfach zu machen, seinen Code hochzuladen ohne alles kaputt zu machen. Bei Git gibt es kein zentrales Repository, sondern viele verteilte Branches die untereinander ausgetauscht werden können.

Git ist Open Source und wurde ursprünglich für die Quellcode-Verwaltung des Linux-Kernels entwickelt. Durch eine Lizenzveränderung des damals benutzten BitKeeper-Systems, konnten die Linux-Entwickler dies nicht mehr kostenlos verwenden, weshalb der Linux-Erfinder Linus Torvalds 2005 mit der Entwicklung einer neuen Quellcode-Management-Software begann, „because I hate CVS with a passion“. (Zitat aus seinem Vortrag bei Google Talks 2007, sehr empfehlenswert und sehr lustig, besonders seine grandiosen Slides :))

[youtube http://www.youtube.com/watch?v=4XpnKHJAok8]

Weiterlesen

Schöne Slideshows – einfach umgesetzt für Web und Mobil

Ein Geheimtipp in Sachen Slideshows für alle, die das nicht selber programmieren können oder wollen, sind die Skripte von bretteleben.de. Der Autor Andreas Berger stellt diese kostenlos zur Verfügung, hat eine gut verständliche Bedienungsanleitung dazu geschrieben und bietet bei Fragen einen beispielhaften Support an.

Die Slideshows gibt es als JavaScript-Code, der mit einem div in jede CSS- oder HTML-Seite eingebunden werden kann. Dazu wird einfach die Datei be_slide.js im HEAD-Bereich der Seite verlinkt und dann im BODY-Bereich der Seite an der gewünschten Stelle ein DIV-Container eingefügt, der die Slideshow enthalten wird. Der Container kann beliebig positioniert und formatiert werden. Damit sind in der Seite selbst bereits alle nötigen Vorbereitungen getroffen. Jetzt können Bilder in einem Ordner Pics abgelegt werden und in dem heruntergeladenen JavaScript-File „be_slide.js“ können noch die einzelnen Parameter entsprechend der gewünschten Verwendung gesetzt werden. Das wars. Übrigens ist die Slideshow auch als Plugin für Joomla verfügbar.

Es ist ein super schlankes Skript mit optimaler Funktion und die Kommentare von Nutzern sind durchweg positiv. Das Skript läuft in allen Browsern und Betriebssystemen und auch auf mobilen Geräten hervorragend. Es kann sehr gut und ohne große Programmierkenntnisse auf die eigenen Bedürfnisse  angepasst werden. Damit ist es sehr vielseitig.

Weiterlesen

System-Monitoring mit JMX und Jolokia

Eine einfache Monitoring-Plattform zum Überwachen einer Java-Anwendung kann mit Hilfe einiger OpenSource-Tools leicht erstellt werden. Dafür werden folgende Komponenten benötigt: Das JMX-Framework, evtl. eine Möglichkeit zum entfernten Zugriff auf die Anwendung, hierzu wird Jolokia vorgestellt, und ein Framework zum Darstellen schöner Diagramme auf der Monitoring-Webseite.

Was ist JMX?

JMX steht für Java Management Extension und ist eine vom Java Community Process (JSR-3) entwickelte Spezifikation zur Verwaltung und Überwachung von Java-Anwendungen. Teile der JMX Spezifikation sind bereits in der Java 1.5 Standard-API integriert und wurden mit Java 6 stark erweitert. JMX ist nicht nur eine geeignete Technologie, um das Verhalten von Systemen zu kontrollieren, sondern erleichtert auch die Kommunikation von unterschiedlichen Java-Programmen. In der ursprünglichen API unterstützte JMX nur die Kommunikation innerhalb einer JVM (Java Virtual Machine), aber seit der Java Version 6 wird auch die Kommunikation mit anderen JVMs unterstützt.

Die Systemdaten werden von sogenannten MBeans ausgelesen. Diese Java-Objekte werden von speziellen Agents verwaltet oder es kann (wenn die Sicherheitsbestimmtungen das zulassen) auch direkt auf die MBeans zugegriffen werden. Es lassen sich statische (z.B. Betriebssystemdaten) und dynamische (Speicherverbrauch, geladene Klassen..) Systemdaten auslesen. Es stehen fertige HTTP-Adapter für JMX zur Verfügung, wodurch es möglich ist, direkt über einen Webbrowser Werte einer Java-Anwendung zu verändern und auszulesen.

Weiterlesen