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/

Vorschau von Confluence-Seiten in JIRA-Tickets anzeigen

Es ist ein recht übliches Vorgehen, dass Anforderungsdokumente sowohl in Confluence abgelegt und bearbeitet werden, als auch noch Tickets in JIRA erstellt werden, um die Anforderungen verfolgen und auswerten zu können. Produktmenschen arbeiten nunmal vielfach lieber mit dem featurereichen Editor im Wiki, als in einem JIRA-Beschreibungsfeld und Entwickler brauchen diese Informationen aber auch direkt in ihrem Arbeitstool JIRA. Dies führt dann dazu, dass Inhalte entweder an zwei Stellen gepflegt werden müssen oder in dem JIRA-Ticket nur ein Link auf die entsprechende Confluence-Seite verweist und damit unnötiges Context-Switching provoziert wird.

Wäre es nicht schön, wenn man die Confluence-Seite einfach als Vorschau in das JIRA-Ticket integrieren könnte?

Mit folgenden Schritten lässt sich dies mühelos bewerkstelligen, allerdings wird dazu das ScriptRunner Plugin von Adaptavist benötigt. Dies war bis vor kurzem kostenlos, ist jetzt aber leider mittlerweile kostenpflichtig.

Mit dem Plugin ScriptRunner lassen sich unter anderem in JIRA programmierbare benutzerdefinierte Felder anlegen. Zunächst wird ein normales URL-Feld mit dem Namen „Confluence URL“ angelegt, in welches der Nutzer die URL der Confluence-Seite eintragen kann.

url-field

Weiterlesen

AtlasCamp 2015: Developers united in Prague

Tigertech@AtlasCamp 4 NetworkedAssets

Every year more developers are coming to get involved into the Atlassian Plugin Developer community. They come to get information about the newest API changes, have the possibility to promote their plugins or ask about difficulties they have had and of course meet with other developers and Atlassians to exchange experiences. In the 8th year of AtlasCamp the community has grown from a small family of around 50 developers to 340+ developers from all over the world, Atlassians not included (also almost 50, so a total number of around 400 participants have been present). Some people are coming every year, but more than half of the participants were joining for there first ever AtlasCamp. And some have become almost more famous than Atlassians themselves. As Co-Founder Mike Cannon-Brookes put it in his welcome speech, there are more people who want a picture with Bob Swift than with himself by now.

Over the last years Europe has been settled as the place to be for the conference, because still most of the developers are coming from Europe. Prague was a great location to choose, but sadly the hotel was 7 kilometers out of town, so there was not much time to walk around the beautiful old city center of prague. But the AtlasParty on wednesday night was still a highlight, taking place directly at the waterfront of the Moldova with a great view over the beautiful charles bridge. A great atmosphere with funny talks.. and a magician or magical plugin dev from sweden doing fascinating performances, which were not including a lot of drinking but the good old string tricks 🙂

AtlasCamp 2015

A new arrangement were the two tracks of talks this year. One track was the more technical part with insights into plugin development strategies and APIs, the other track was more general about best practices in coding. This was somehow nice, because you could choose between 2 topics in every slot, but also you were missing of course half of them and sometimes it was a hard decision. Also new were the developer breakout sessions after the main talks, in which plugin developers were intruducing into topics of their choice and from their work. These offered great insights and also a good opportunity to get into conversation with each other in small groups. The camp has become more structured and professional, for example there were almost no problems with the Wifi-connection this year and live demos were not live anymore, but all from screencasts.. which was a shame somehow, because most of the time live demos really live from the live kind of thing and the errors that can be made 🙂 2015-06-10 09.51.53 Weiterlesen

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

Lisp für Anfänger – Alles ist eine Liste

Da ich in letzter Zeit schon mehrfach Wundersames über die Programmiersprache Lisp gelesen habe, wollte ich nun endlich selbst ausprobieren, was es damit auf sich hat. Bei Lisp denken die meisten erstmal an furchtbar viel Mathe oder an eine uralte Sprache, die heute wohl kaum noch einer benutzt. Richtig ist, daß der Kreis der Lisp-Programmierer eher eine verschworene kleine Gemeinschaft als eine große Mainstream-Bewegung ist und der Ursprung der Sprache basiert ganz klar auf mathematischen Grundlagen. Trotzdem ist der Einstieg nicht schwer und jeder kann das mit einfachen Mitteln ausprobieren. Die schlichte Schönheit der Sprache lässt sich dabei schnell erkennen.

lisplogo

Paul Graham sieht die nach wie vor geringe Verbreitung von Lisp als Wettbewerbsvorteil für Lisp-Programmierer an. Konkurrenten müssten nach Graham in sogenannten „Blub-Sprachen“ programmieren und wären dadurch weit weniger flexibel in der Entwicklung. Dies ist natürlich recht überheblich formuliert, allerdings betonen doch eigentlich alle Lisp-Programmierer, welche Vorteile Lisp gegenüber allen anderen Sprachen hat und warum eben diese anderen Sprachen niemals genau diese Vorteile haben werden. Es sei denn, man baut sie zu Lisp um 🙂 Jeder mag natürlich die Sprache die er am besten kann am liebsten, dennoch lohnt es sich eigentlich immer über den Tellerrand hinauszuschauen.

john_mccarthyLisp wurde 1958 erstmals von John McCarthy am Massachussets Institute of Technology (MIT) als theoretische Erforschung einer mathematischen Syntax spezifiziert. Einer seiner Studenten implementierte dies schließlich als Programmiersprache. Seitdem wurden zahlreiche Lisp-Dialekte entwickelt, doch die Basis blieb stets dieselbe. Nach Fortran ist Lisp die zweitälteste Programmiersprache, die noch in Verwendung ist.

Der Begriff Lisp bedeutet „List Processing“  (Listen-Verarbeitung) und tatsächlich ist in Lisp alles eine Liste. Listen können beliebig verschachtelt sein und es läßt sich alles damit ausdrücken. So sind auch Programmanweisungen Listen, wobei das erste Element der Liste die auszuführende Funktion darstellt. Dies kann zum Beispiel ein Operator sein, wie bei Addition oder Multiplikation:

(* 3 (+ 2 5))

Wer als Ergebnis 21 herausbekommt, hat das Prinzip schon verstanden 🙂

Weiterlesen

JIRA-Administration: Anzeigen von benutzerdefinierten Werten in Scripted Custom Fields

Für JIRA-Vorgänge lassen sich standardmäßig jede Menge benutzerdefinierte Felder hinzufügen, die jedoch vom Bearbeiter dann manuell ausgefüllt werden müssen. Um in benutzerdefinierten Feldern automatisch Werte anzeigen zu lassen (read-only), die auf Berechnungen auf Werten aus der Datenbank basieren, können Scripted Custom Fields verwendet werden.

In folgendem Beispiel wird ein Feld zu einem JIRA-Vorgang hinzugefügt, in welchem angezeigt wird, wie lange sich ein JIRA-Ticket in einem bestimmten Workflow-Status befunden hat. Dies ist beispielsweise für die Ausgabe eines Berichts über die Bearbeitungsdauer der Tickets in einem Projekt interessant. Alle Felder können nämlich auch in Spalten eines Excel-Exports oder in Diagrammen auf dem Dashboard angezeigt und ausgewertet werden.

Hierzu muss zunächst das kostenlose Script-Runner-Plugin in der JIRA-Instanz installiert werden.

Als nächstes wird in der System-Administration von JIRA ein neues benutzerdefiniertes Feld angelegt. Um die Zeit des Vorgangs in dem Status „In Progress“ zu berechnen, erstellt man ein Feld „Time In Progress“ und benutzt dafür den durch das Plugin hinzugefügten neuen Typ „Scripted Field“.

scriptedfields3

Weiterlesen

Off Topic: Wie entlarvt man schlechte Wissenschaft

bad_science1Immer wieder stolpert man als wissenschaftlich interessierter Leser über dubiose Statistiken oder pseudowissenschaftliche Hinweise in den Medien, die einem die Frage aufdrängen, woher diese Informationen stammen und ob das alles überhaupt so richtig ist. Mit Formulierungen wie „wissenschaftliche Untersuchen haben gezeigt..“ oder „laut neuesten wissenschaftlichen Erkenntnissen..“ werden hin und wieder populistische Schlagzeilen gemacht, die in etlichen Fällen schlecht recherchiert oder masslos übertrieben dargestellt sind. Dabei ist es überhaupt nicht problematisch, wenn ein Journalist ein wissenschaftliches Thema massentauglich aufbereitet, oder sich dabei irrt, allerdings wird es kritisch, wenn dahinter Interessen Dritter zu vermuten sind, die die Neutralität der Medien in Frage stellen. Ohne paranoid zu werden, kann man mit ein Paar Analysen etliche dieser Fälle sofort erkennen.

Ben Goldacre

Ben Goldacre

Der britische Arzt und Journalist Ben Goldacre hat es sich zur Aufgabe gemacht, solche Fälle aufzuklären und anzuprangern, aber auch Lesern, die nicht ganz so tief in der Materie stecken wie er, Werkzeuge an die Hand zu geben, um derartige „schlechten Wissenschaften“ zu entlarven. Ein gesundes Misstrauen ist hierbei eine wichtige  Voraussetzung. Danach müssen gewisse wissenschaftliche Basisvorraussetzungen geprüft und angegebene Referenzen gecheckt werden. Mit ein paar einfachen Tests läßt sich so mancher wissenschaftliche Artikel als fragwürdig entlarven.

Weiterlesen

Skype dauernd online – Schnelle Lösung

Bei der Nutzung von Skype auf vielen verschiedenen Geräten (dem Handy, dem Tablet, einem Rechner auf der Arbeit, einem zu Hause und dann vielleicht noch auf einem Arbeitstelefon), kann es passieren, daß man ungewollt auf Skype dauernd als online verfügbar angezeigt wird. Selbst nachdem Skype auf allen Geräten ausgeschaltet wurde, war mein Account über Wochen online und die Leute ärgerten sich, daß ich nicht antwortete. Nach einigem recherchieren bin ich endlich auf eine schnelle Lösung gestossen, die es einem auch zwischendurch mal ermöglicht, kurz zu überprüfen, mit welchen Geräten man eigentlich gerade angemeldet ist.

Hierzu öffnet man ein Skype-Chat-Fenster mit einem beliebigen Kontakt und tippt dort

/showplaces

ein.

Weiterlesen

Developers united in Berlin – AtlasCamp 2014

AtlasCamp is the yearly conference for Plugin Developers of Atlassian products, which provides insights in the product APIs, informs about new features and of course is a great opportunity to get to know each other.

With Berlin Atlassian chose a great location for developers to meet and enjoy the sunny weather with about 30 degrees and interesting talks with a very international audience. A quick research unvailed that more than 50% of the attendees were new to AtlasCamp, which means that the community is still growing fast. There was no hackathon during the camp this year, but a competition for developers in advance to present their latest Atlassian Connect Add-on and win a price. I guess that was because some developers were complaining about missing all of the conference while hacking away for the hackathon last year. So even though it was fun having intensly working people around in Amsterdam, it was much more laid back this year and talking and getting connected was more in focus of the event. Also the Wifi-Connection at the Maritim-Hotel was so bad, that nobody was really able to work, but had to stay offline with the surrounding participants to talk (Lächeln)

atlascamp2014atlascamp2014atlascamp2014

2014-06-04 20.01.56

Weiterlesen