Archive | March, 2012

Wikis bringen Multimedia in die Dokumentation

29 Mar

Willkommen im HTML 5 Zeitalter. Es war nie einfacher Dokumentation mit Daten aus anderen Systemen zu verknüpfen und zu publizieren. Der Einsatz von Wikis für die Softwaredokumentation macht auch aus diesem Grund Sinn. Wer hat denn das letzte mal ein Handbuch für eine Software durchgeblättert? Hier also einige Tipps, wie man Dokumentation und Multimedia miteinander verknüpfen kann.

Bilder nutzen

Mit Bildern bleiben Informationen besser im Gedächtnis haften. Mehr noch: Bilder transportieren Informationen meist besser als nur Text. Man kann Daten kompakter und greifbarer in einem Diagramm unterbringen als ein schriftlicher Form. Zusätzlich wecken Bilder das Interesse der Leser.

Moderne Wikis geben den Editoren die Möglichkeit mit einfachen Mitteln ein Bild hinzuzufügen. Beispielsweise bietet das Enterprise Wiki Confluence eine Drag und Drop Funktion im Browser an, um beispielsweise ein Foto zum Text hinzuzufügen. Aber wo Wikis wirklich herausstechen, ist die Möglichkeit, die Doku mit dynamischen Daten aus anderen Seiten anzureichern.

Multimedialer Inhalt

Hier ein Überlbick, was alles mit modernen Wikis möglich ist

  • Video und Audio: Fügen Sie Multimediadateien zu Seiten hinzu oder betten Sie YouTube oder Vimeo Videos ein. Gerade für Anleitungen ist ein Video oft besser geeignet. Gleiches gilt für Screencasts. Aber: Natürlich ist diese Form der Dokumentation sehr zeit- und pflegeintensiv.
  • Bilder und Diagramme: Screenshots sollten in jeder Softwaredokumentation vorhanden sein. In Confluence ist es auch möglich Gliffy Diagramme direkt auf einer Seite anzuzeigen und zu editieren.
  • Präsentationen und andere Dokumente: Fügen Sie auch PDF-, Powerpoint-, SlideRocket oder Slideshare-Präsentationen zu ihrer Dokumentation hinzu, so dass Benutzer diese direkt auf der Dokuseite durchklicken können. Gleiches gilt für MS-Office Dokumente und GoogleDocs, die nicht erst vom Benutzer heruntergeladen werden müssen, sondern direkt auf der Seite betrachtet werden können.
Technische Redakteure sollten sich diese Funtionen zu nutze machen. Vielleicht hat Ihr Marketing Team gerade ein Anleitungsvideo produziert oder der Kollege aus der Technik hat einen Vortrag auf Slideshare veröffenlticht, der das System erklärt. Fügen Sie einfach diese Resourcen zur Dokumentation hinzu, ohne diese konvertieren zu müssen. Das sind tolle Resourcen für die Leser Ihrer Doku.

Echzeit-Daten

Ihre Seite kann Live-Informationen aus anderen Seiten enthalten. Wenn also Benutzer die Seite öffnen, sehen diese die neusten Informationen, die auf anderen Seiten publiziert worden sind:

  • Gadgets. iGoogle Gadgets bieten die Möglichkeit, beispielsweise eine Übersetzer-App, aktuelle Wetterinformationen, Landkarten und vieles mehr auf einfache Weise auf einer Wiki-Seite zu intgrieren.
  • Aufgabenverfolgung. Reichern Sie Ihre Release Notes mit erledigten Aufgaben aus Ihrer Aufgabenverfolgung an. Die Daten werden dynamisch aus dem Issue Tracker ausgelesen und in ihrer Releaseinformationsseite angezeigt.
  • und noch vieles mehr: Aktivitätsströme, Blogposts, Kalendar…

Twitter + Wiki = Tolle Kombination

Twitter ist für viele Menschen heutzutage die erste Wahl, um Informationen schnell zu verbreiten. Man liest und versendet Informationen im Netz, auf dem Smartphone, auf Facebook, via Email, RSS, spezielle Apps… An jedem Ort, zu jeder Zeit.

Wäre es nicht cool, wenn man technische Informationen über Twitter verschicken könnte? Noch besser: Wie wäre es wenn man Personen über Twitter an die Dokumentation heranführen kann? Atlassian hat mit beiden Sachen experimentiert.

Wir haben Kunden gebeten, über Tipps und Tricks für unsere Produkte zu twittern. Über ein speziellen HashTag teilen die Kunden Informationen mit uns und anderen Kunden. Diese Tweets werden dann auf unseren Doku-Seiten live veröffentlicht. Hier können Sie sich selbst davon überzeugen:

Interaktive und spielerische Dokumentation

Man glaubt es kaum, aber: Technische Doku kann von Spaß und Spiel profitieren. Diesen Gamifaction-Ansatz haben wir bei unserer Dragon Slayer Doku verfolgt. Dabei handelt es sich einfach um eine spielerische Anleitung, wie man Podukte installieren und konfigurieren kann. Die Installation und Konfiguration der gesamten Atlassian Produkte braucht ein wenig Zeit und kann auch mal ziemlich langweilig und tricky werden. Also haben wir Sir Charly von Atlassian, den furchtlose Drachentöter erfunden, der einen durch den Prozess leitet. Die Installation wurde dafür in verschieden Abschnitte unterteilt, an dessen jeweiligem Ende man über die Erfahrungen twittern soll.

“Fare ye well, brave souls and true. I’m starting the Atlassian Dragon Quest!”

Wir haben durchweg gute Erfahrungen mit der Einführung von Social Media – Fuktionalität in unserer Dokumentation mit Conflucence gemacht. Die Kunden schätzen die offene Kommunikation und lieben die Echtzeit-Funktionen.

Was für weitere Vorteile ein Wiki für die Softwaredokumentation im Team bietet, kann man hier nachlesen.

Tags: , , , , , , , ,

Software-Dokumentation im Team erstellen mit Wikis

13 Mar

Das gemeinsame Erstellen von Anforderungsdokumenten kennt man ja als Softwareentwickler: Der Product Owner schreibt, der Entwickler ändert oder kommentiert. Nach ein paar Schleifen steht dann ein fertiges Dokument. Wenn man aber technische Dokumentation erstellt, sind noch eine Menge mehr Leute involviert: Technische Redakteure, Entwickler, Marketing, Support und Endanwender. Das gibt oftmals ein ganz schönes Chaos, oder wird in einigen Unternehmen so strikt gehandhabt, dass die Dokumentation oft starr und veraltet wirkt.

Die Vorteile eines Wikis nutzen

Wir bei Atlassian benutzen das Enterprise Wiki Confluence zur Dokumentation unserer Software (-> Dogfooding: auch für Confluence). Wir haben 2 Seiten, die wir pflegen: Atlassian Anwender Doku und Atlassian Developer Doku. Bei uns erstellen neben den technischen Redakteuren auch Entwickler und Support die Dokumentation (und machmal auch unser CEO). Da wir nur 7 Redakteure haben, ist dies auch notwendig. Dazu kommen noch ca. 50 Helfer aus unserer Community.
Der Vorteil des Einsatzes eines Wikis sehen wir auch darin, dass Dokumentation und Zusammenarbeit unabhängig von geografischen Hürden und Zeitzonen erstellt werden kann. Ein Wiki steht immer und überall zur Verfügung.

Verantwortung übernehmen

Rechte: Es macht Sinn, an einigen Stellen die Rechte zu beschränken. In Confluence kann man Gruppen wie Entwickler, Redakteure und Community einrichten und die Rechte in verschiedenen Bereichen unterschiedlich vergeben.
Informiert sein: Man sollte immer über Änderungen informiert sein. Meist bieten Wikis einen Machanismus an, damit man über Email oder RSS-Feed immer auf dem Laufenden bleibt. Sie können dann regieren, wenn sie Zeit haben
Menschen beteiligen: Teilen Sie Inhalte anderen Personen mit und lassen sie diese an der Erstellung der Dokumentation teilhaben.
Verschicken Sie einen Link per Email oder benutzen sie die “Teilen”.-Funktion von Confluence. Die angesprochene Person kann sich dann einfach im Wiki einloggen und Inhalte verändern oder kommentieren.
Auch mal löschen: Hat jemand am Thema vorbeigeschrieben, oder ist eine Seite veraltet, sollte man nicht davor zurückschrecken auch mal Inhalte zu verschieben oder zu löschen. So bleibt ihre Dokumentation immer frisch (ist ja auch bei Quellcode so).

Kommentare nutzen

Die Kommentarfunktion ist eine der besten Features moderner Wikis. Man kann direkt in den Dialog mit dem Autor oder anderen an der Doku beitligten Personen einsteigen.

Achtung: Es können recht viele Kommantare werden, stellen Sie deshalb sicher, dass man die nötige Zeit und Resourcen hat, um sich auch darum zu kümmern. Nichts ist schlimmer, als die Kommentarfunktion anzubieten, dann aber nicht auf Anfragen zu antworten!
Nicht nur Dokumentation: Es werden meist nicht nur Kommentare zur Dokumentation gestellt. Meist sind es Fragen technischer Natur. Die technischen Redaktuere sollten sich also hier durch die Entwicklung unterstützen lassen.
Gegenseitige Hilfe: Das Beste, was passieren kann, ist, wenn eine Community entsteht, die sich gegenseitig hilft. Es gibt immer Fan-Boys der Produkte, die gerne anderen helfen möchten. Dadurch braucht auch die technische Redaktion weniger Resourcen. Unterstützen und bekräftigen sie ihre größten Fans.
Kommentar nicht erwünscht? Auf einigen Seiten machen Kommentare keinen Sinn oder sind nicht erwünscht. Schalten Sie die Kommentarfunktion für solche Bereiche ab.
Nett bleiben: Beiben Sie bei Antworten immer nett und höflich. Antworten Sie direkt und bestimmt, so wird ihre Wiki-gestützte Dokumentation zu einer guten Kommunikationsplattform.
Kommentare löschen: Ist eine Frage beantwortet, kann sie auch wieder nach einiger Zeit gelöscht werden. Passen Sie also ihre Doku an, wenn es hier ein Missverständnis gab, oder einige Dinge beschreiben wurden. Zu viele Kommentare lenken von der Dokumentation ab und helfen dem Benutzer nicht weiter, da diese meist nicht strukturiert sind. Wir löschen geklärte Kommentare bei Atlassian in der Regel nach 14 Tagen.

Die Verbindung halten

Wikis verbinden Menschen und verschiedene Aufgaben im Unternehmen miteinander. Gemeinsam kann man eine außergewöhnliche und frische Dokumentation erstellen. Ihre Nutzer werden es klasse finden, wenn Sie direkt mit Ihnen über Inhalte diskutieren können. Aber auch für Kollaboration im Unternehmen sind Dokumentationen in Wikis erstklassig geeignet.

Mehr über technische Dokuemtation mit Confluence gibt es auf unserer Webpage oder in Sarah Maddox Buch “Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication”

Tags: , , , , , , ,

6 Tipps zu einer guten Online-Präsenz für Softwareentwickler

5 Mar

Es gibt eine Menge Softwareentwickler auf der Welt, aber nur eine begrenzte Anzahl cooler Jobs. Wie kann man also am erfolgreichsten auf sich aufmerksam machen, ohne dass man gleich 18 Stunden am Tag arbeitet? Hier sind einige Ideen:

1. Teile deinen Code mit anderen

Personalabteilung schauen sich gerade bei einer Vielzahl von Bewerbungen immer öfter im Internet um. Der am meisten genutzte Weg ist wohl sich Code der Kandidaten aus Github oder Bitbucket anzuschauen.

Es ist keine Überraschung, dass zukünftige Arbeitgeber sich nach Bewerbern umschauen, die guten und sauberen Code schreiben können. Aber wie viel Code kann man schon in eine Bewerbung packen?

Entwickler sollten die Vorteile daran erkennen, ihre privaten Projekte öffentlich mit anderen zu teilen. Das ist eine gute Möglichkeit seine Interessen und Fähigkeiten zu präsentieren.

Gute Arbeitgeber halten auch nach aktiven Committern von Open Source Projekten Ausschau, um den Entwickler besser beurteilen zu können. An einem Open Source Projekt zu arbeiten, zeigt unter anderem deine Qualitäten im Team zu arbeiten. Es geht als nicht nur darum guten Code zu schreiben, sondern auch gut mit der User-Gemeinde zu kommunizieren.

2. Stelle Verbindungen her

Bei Xing und LinkedIn kann man einfach seinen Lebenslauf online stellen und sich mit interessanten Menschen verbinden. Man sollte allerdings seine Daten immer aktuell halten und auch die Beteiligung an Communities erwähnen. Das rundet dein Gesamtbild ab.

3. Get social

Ich habe Twitter nicht von Anfang an verstanden, bis ich Tweetdeck entdeckt habe. Solche Tools helfen einem das Rauschen zu reduzieren und Twitter zu einem exzellentem Research- und Kommunikationstool zu machen. Egal, ob ein interessantes Ereignis ansteht, es einen neuen interessanten Artikel zu lesen gibt oder ob für ein Tool ein neues cooles Update bereitsteht – auf Twitter liest man es zuerst.

Mit Twitter kann man interessanten Personen folgen, oder interessanten Hash-Tags, wie z.B. #Openjdk oder #Atlassian ;-) . Viele Veranstaltungen benutzen ein Hash-Tag. Es ist also einfach Feedback zu geben oder Erfahrungen von diesen Events weiterzugeben.

Twitter tools: Hootsuite (web 2.0), Tweetdeck (Desktop und mobile App)

4. Vergiss nicht, deine Erfahrungen weiterzugeben…

Dein Quellcode erzählt nicht die ganze Geschichte (auch wenn Uncle Bob uns das immer weismachen möchte). Du solltest deine Gedanken, Meinungen und Ideen anderen Leuten mitteilen.

Interessante Blogs sollten Aspekte aufzeigen, an die man noch nicht gedacht hat, oder Tools und Techniken vorstellen, die für die Leser interessant sein könnten. Erzähle den Leuten deine Geschichte, was du gelernt hast. Versuch eine Diskussion zu starten, ohne andere gleich mit deiner Meinung vor den Kopf zu stoßen.

Lies andere Weblogs und trete in die Kommunikation ein. Wenn du eine Meinung hast, teile diese dem Autor über die Kommentarfunktion mit.

Gute Blog-Tools: blogger.com , wordpress.com

5. Komm auch mal weg vom Bildschirm

Ein Teil der technischen Community zu sein, bedeutet auch, sich außerhalb des Internets zu bewegen und Offlineverbindungen zu Personen aufzubauen. Wirklich von Angesicht zu Angesicht über die neusten Trends, Technologien oder Programmiersprachen zu sprechen macht viel mehr Spaß. Es gibt viele technischen Communities in jeder größeren Stadt in Deutschland. Xing und Meetup.com sind gute Plattformen, um sich über Communities zu informieren und die Termine zu den Treffen zu erfahren.

Lanyrd ist social Konferenzplattform auf der viele Communities ihre Events einstellen und managen. Man kann sich dort auch über die Sprecher und Vorträge informieren, oder wer sonst noch an der Konferenz teilnimmt. Lanyrd ist auch ein großartiges Tool um sein eigenes Profil als Sprecher aufzubauen ;-)

6. Lightning Talks und Vorträge halten

Man sollte keine Angst davor haben vor Leuten zu sprechen, wir sind alle Geeks. Es ist wie mit allen Dingen, je mehr man vorträgt, desto sicherer wird man. Beginne einfach mit Themen, über die du wirklich viel weisst und mache eine kleine Präsentation, z.B. ein 5-Minuten Lightning Talk.

Auf Community Events zu sprechen ist ein gute Möglichkeit vor einem dir freundlichem Publikum zu stehen und positives Feedback zu bekommen.

Also keine Angst: Einfach mal ins kalte Wasser springen und loslegen… So etwas macht sich auch gut im Lebenslauf.

Event tools: Meetup.com, Lanyrd, Buch: Bekenntnisse eines Redners

Follow

Get every new post delivered to your Inbox.

Join 26 other followers