Author: mbarkhau
Date: Thu Aug 9 15:59:29 2007
New Revision: 929
Log:
Review of ch02 up to developer documentation
Modified:
trunk/de/ch02.xml
Modified: trunk/de/ch02.xml
==============================================================================
--- trunk/de/ch02.xml (original)
+++ trunk/de/ch02.xml Thu Aug 9 15:59:29 2007
@@ -536,116 +536,113 @@
<sect2 id="downloads">
<title>Downloads</title>
-<para>Die Software sollte als Quellcode in Standard Formaten
-herunterladbar sein. Wenn ein Projekt noch am Anfang ist, sind
-binär(ausführbare) Dateien noch nicht notwendig, es sei denn der
+<para>Man sollte den Quellcode der Software in den üblichen Formaten
+herunterladen können. Wenn ein Projekt noch am Anfang ist, sind
+binäre (ausführbare) Dateien noch nicht nötig, es sei denn der
build Vorgang ist derart kompliziert und voller Abhängigkeiten, dass
es für die meisten Leute einen menge Arbeit wäre die Software
-überhaupt zum laufen zu bringen. (Wenn das allerdings der Fall ist,
-wird das Projekt es eh schwer haben Entwickler an zu locken.</para>
+überhaupt zum laufen zu bringen. (Wenn das aber der Fall ist, wird
+das Projekt es eh schwer haben Entwickler anzulocken.</para>
-<para>Die Verbreitungsmethode sollte so bequem, standardkonform und
-so wenig Overhead wie möglich haben. Wenn Sie eine Krankheit
-ausrotten wollten, würden Sie nicht die Medizin derart verbreiten,
-dass eine unüblich Spritzengröße bräuchte. Ebenso sollte Software
-die üblichen build und installations Methoden befolgen, denn je
-mehr die Software von diesen Standards abweicht, desto größer ist
-das Potential Benutzer und Entwickler aufgeben werden und verwirrt
-weg gehen.</para>
+<para>Die veröffentlichten Dateien herunterzuladen sollte möglichst
+bequem, standardkonform und mühelos sein. Wenn Sie eine Krankheit
+ausrotten wollen, würden Sie nicht die Medizin derart verteilen,
+dass man eine unüblich Spritze bräuchte. Ebenso sollte Software die
+üblichen build- und installations-Methoden beachten, denn je mehr die
+Software von diesen Standards abweicht, desto größer ist das Potential,
+dass Benutzer und Entwickler aufgeben und verwirrt weggehen.</para>
<para>Das hört sich sehr offensichtlich an, aber viele Projekte machen
-sich sehr lange nicht diese Mühe und sagen sich, dass sie es jeder
-Zeit machen könnten: <emphasis>"Wir erledigen den Kram dann wenn der
-Code näher an der Fertigstellung ist".</emphasis> Was sie dabei nicht
-erkennen, ist dass indem sie die langweilige Arbeit, die
-Fertigstellung der Installationvorgänge, hinauschieben, sie auch
-die Fertigstellung des Codes verlangsamen-da sie Entwickler
-entmutigen, die ansonsten zum Code beigetragen hätten. Das
-heimtückischste dabei ist, dass sie nicht <emphasis>wissen
-</emphasis>, dass sie all diese Entwickler verlieren, da der Vorgang
-eine Anhäufung Nicht-Ereignissen ist: Jemand geht auf die Webseite,
-lädt die Software herunter, versucht sie zu builden, scheitert, gibt
-auf und geht weg. Wer wird jemals davon was wissen, außer die Person
-selbst? Keiner der am Projekt arbeitet, wird bemerken, dass jemandem
-Interesse und Wohlwollen stumm verschwendet wurde.</para>
-
-<para>Langweilige Arbeit, mit einem hohen Gewinn sollte immer früh
-erledigt werden und die Einstiegshürde zu einem Projekt, durch
-gutes Packaging zahlt sich vielfach zurück.</para>
-
-<para>Wenn Sie eine herunterladbare Version herausgeben, ist es
-wichtig, dass Sie Ihr eine eindeutige Versionsnummer geben, damit
-Leute beide Versionen unterscheiden können und wissen welche auf
-die andere Folgt. Eine ausführliche Diskussion zu Versionsummern
+sich sehr lange nicht diese Mühe und sagen sich, dass sie es jederzeit
+machen könnten: <emphasis>"Wir erledigen den Kram sobald der Code näher
+an der Fertigstellung ist.".</emphasis> Was sie dabei nicht erkennen,
+ist dass indem sie die langweilige Arbeit hinauschieben, wie die
+Fertigstellung der Build- und Installationvorgänge, schieben sie auch
+die Fertigstellung des Codes hinaus—denn sie entmutigen
+Entwickler, die ansonsten zum Code beigetragen hätten. Das
+heimtückischste daran ist, dass sie nicht <emphasis>wissen</emphasis>,
+dass sie all diese Entwickler verlieren, denn der Vorgang ist eine
+Ansammlung von Nicht-Ereignissen: Jemand geht auf die Webseite, lädt
+die Software herunter, versucht einen Build zu machen, scheitert, gibt
+auf und geht weg. Wer wird jemals davon etwas wissen, außer die Person
+selbst? Keiner im Projekt wird je bemerken, dass das Interesse und
+Wohlwollen von jemand stumm verschwendet wurde.</para>
+
+<para>Langweilige Arbeit, mit einem hohen Nutzen sollte immer früh
+erledigt werden und die Einstiegshürde zu einem Projekt, durch gutes
+Packaging zu veringern, zahlt sich um Vielfaches zurück.</para>
+
+<para>Wenn Sie eine Version zum herunterladen veröffentlichen ist es
+wichtig, dass Sie eine eindeutige Versionsnummer vergeben, um alle
+Versionen von einander unterscheiden zu können und klar ist welche
+aufeinander Folgen. Eine ausführliche Diskussion über Versionsnummern
finden Sie in <xref linkend="release-numbering"/>, und Details zur
-Standardisierung eines der build und Installationsvorgänge werden in
-<xref linkend="packaging"/><phrase output="printed">, sowie
+Standardisierung eines der Build- und Installationsvorgänge werden im
+Abschnitt <xref linkend="packaging"/><phrase output="printed">, sowie
in <xref linkend="development-cycle"/></phrase> behandelt.</para>
</sect2>
<!-- ======================== subsection ============================== -->
<sect2 id="vc-and-bug-tracker-access">
-<title>Zugriff zur Versionskontrolle und dem Bug Tracker</title>
+<title>Zugriff auf die Versionsverwaltung und den Bug-Tracker</title>
-<para>Quellcode Pakete herunter zu laden reicht für diejenigen aus,
-die die Software lediglich installieren und benutzen wollen, aber es
-reicht nicht für diejenigen die die Software debuggen und neue
+<para>Quellcode Pakete herunterzuladen reicht für alle aus, welche
+die Software lediglich installieren und benutzen wollen, aber es
+reicht nicht für diejenigen aus die daran arbeiten, debuggen und neue
Funktionen hinzufügen wollen. Nächtliche Quellcode Snapshots können
-helfen, sind aber immer noch nicht fein granuliert genug für eine
-gedeihende Entwicklergemeinschaft. Diese Leute brauchen Echtzeit Zugriff
-auf den neusten Quellcode und der Weg ihnen dieses zu geben, ist ein
-Versionskontroll System zu benutzen. Das Vorhandensein von anonym
-erreichbaren Quellcode welches unter Versionskontrolle liegt ist ein
-Zeichen-sowohl für Entwickler wie Benutzer-, dass das Projekt sich
-mühe gibt Leute das nötige zu geben, um sich zu beteiligen. Wenn Sie
-nicht sofort Versionskontrolle zur Verfügung stellen können, stellen
-Sie zumindest ein Schild auf, dass darauf hinweist, dass Sie es bald
-vor haben. Infrastruktur für Versionskontrolle wird ausführlich in
-<xref linkend="vc"/><phrase output="printed"> und
-<xref linkend="technical-infrastructure"/></phrase> behandelt.</para>
-
-<para>Selbiges gilt für den Bug Tracker des Projekts. Ein Bugtracker
-ist nicht nur wichtig auf Grund seiner Nützlichkeit für Entwickler,
-sondern auch für die Botschaft die es Beobachter gibt. Für Viele,
-ist eine offene Bug Datenbank eines der stärksten Anzeichen, dass ein
-Projekt ernst genommen werden sollte. Desweiteren, ist das Projekt um
-so besser, je mehr Fehler darin protokolliert wurden. Auch wenn es sich
-widersprüchlich anhört, sollte man bedenken das die Anzahl der
-erfassten Bugs von drei Sachen abhängt: die absolute Anzahl der Bugs
-in der Software, die Anzahl der Benutzer der Software und wie bequem es
-für diese Benutzer ist, neue Bugs einzutragen. Von diesen dreien sind
-die letzten beide die wesentlicher als der erste. Jede Software von
-einer wesentlichen Größe und Komplexität, enthält eine Grunde
-genommen beliebige Anzahl an Bugs, die darauf warten entdeckt zu
-werden. Die wirkliche Frage ist, wie gut ist das Projekt darin, diese
-Bugs zu erfassen und zu priorisieren? Ein Projekt mit einer großen
-und gut gepflegten Bug Datenbank (was so viel heißt wie, dass schnell
-auf Bugs reagiert wird, Duplikate vereinigt werden, usw.) macht
-deshalb einen besseren Eindruck als ein Projekt ohne Bug Datenbank
-oder einer fast leeren Datenbank.</para>
-
-<para>Wenn Ihr Projekt erst anfängt, wird die Bug Datenbank natürlich
-nur sehr wenige Bugs enthalten und es gibt nicht viel, was Sie dagegen
-machen können. Wenn die Status Seite aber sein junges Alter hervorhebt
-und wenn Leute die auf die Bug Datenbank schauen sehen können, dass
-die Meisten Einträge neulich gemacht wurden, können sie sich
-ausrechnen, dass das Projekt immer noch eine gesunde <emphasis>rate
-</emphasis> an Einträgen hat und werden dementsprechend nicht
-übermäßig alarmiert über die niedrige absolute Anzahl an Bugs sein.
-</para>
-
-<para>Es sollte auch beachtet werden, dass Bug Tracker oft nicht nur
-zur Verfolgung von Bugs benutzt werden, sondern auch für
-Verbesserungen an der Software, Veränderungen an der Dokumentation
-ausstehende Aufgaben und weiteres benutzt werden. Weiteres zum
-Betrieb eines Bug Trackers, wird in
-<xref linkend="bug-tracker"/><phrase output="printed"> und
-<xref linkend="technical-infrastructure"/></phrase>behandelt, also
-erde ich hier nicht näher darauf eingehen. Das wichtige aus Sicht
-der Präsentation ist überhaupt einen Bug Tracker zu <emphasis>haben
-</emphasis> und sicher zu stellen, dass er von der Hauptseite auch
-sichtbar ist.</para>
+helfen, sind aber immer noch nicht fein genug granuliert für eine
+gedeihende Entwicklergemeinschaft. Diese Leute brauchen Echtzeit-Zugriff
+auf den neusten Quellcode und der Weg es ihnen zu geben, ist eine
+Versionsverwaltung zu benutzen. Anonym erreichbarer Quellcode der unter
+Versionsverwaltung steht ist ein Zeichen—für Entwickler wie
+Nutzer—dass das Projekt sich mühe gibt Leute das nötige zu geben,
+um sich zu beteiligen. Wenn Sie nicht sofort eine Versionsverwaltung
+bereitstellen können, sollten Sie zumindest darauf hinweisen, dass Sie
+es bald vorhaben. Die Infrastruktur der Versionsverwaltung wird
+ausführlich in <xref linkend="vc"/><phrase output="printed"> des
+Kapitels <xref linkend="technical-infrastructure"/></phrase>
+behandelt.</para>
+
+<para>Gleiches gilt für den Bug-Tracker. Ein Bug-Tracker ist nicht nur
+wichtig wegen seiner Nützlichkeit für Entwickler, sondern auch für seine
+Botschaft an Beobachter. Für Viele, ist eine offene Bug Datenbank eines
+der stärksten Anzeichen, dass ein Projekt ernst genommen werden sollte.
+Desweiteren, ist ein Projekt um so besser, je mehr Fehler darin
+protokolliert sind. Auch wenn es sich widersprüchlich anhört, sollte man
+bedenken das die Anzahl der erfassten Fehler von drei Sachen abhängt:
+die absolute Anzahl in der Software enthaltene Fehler, die Anzahl seiner
+Benutzer und wie bequem es für diese Benutzer ist, neue Fehler
+einzutragen. Von diesen dreien sind die letzten beide die wesentlich
+wichtigen. Jede genügend Große und Komplexe Software, enthält im Grunde
+genommen eine beliebige Anzahl an Fehlern, die nur darauf warten
+entdeckt zu werden. Die eigentliche Frage ist, wie gut kann das Projekt,
+diese Fehler erfassen und priorisieren? Ein Projekt mit einer großen
+und gepflegten Bug Datenbank (was so viel heißt wie, dass schnell auf
+Bugs reagiert wird, Duplikate markiert werden, usw.) macht deshalb einen
+besseren Eindruck als ein Projekt ohne Bug Datenbank oder einer fast
+leeren Datenbank.</para>
+
+<para>Wenn Ihr Projekt erst am Anfang ist, wird die Bug Datenbank
+natürlich nur sehr wenige Bugs enthalten und es gibt nicht viel, was
+Sie dagegen machen können. Wenn die Status Seite aber das junge Alter
+hervorhebt und wenn Leute die auf die Bug Datenbank schauen sehen
+können, dass die Meisten Einträge vor kurzem gemacht wurden, können sie
+sich ausrechnen, dass das Projekt immer noch eine gesunde
+<emphasis>Rate</emphasis> an Einträgen hat und werden dementsprechend
+nicht übermäßig alarmiert sein, über die niedrige absolute Anzahl an
+Bugs.</para>
+
+<para>Man sollte auch beachten, dass Bug-Tracker oft nicht nur zur
+Verfolgung von Bugs, sondern auch für Verbesserungen an der Software,
+Änderungen an der Dokumentation ausstehende Aufgaben und mehr benutzt
+werden. Weiteres zum Betrieb eines Bug-Trackers, wird in
+<xref linkend="bug-tracker"/><phrase output="printed"> im Kapitel
+<xref linkend="technical-infrastructure"/></phrase> behandelt, also
+werde ich hier nicht näher darauf eingehen. Das wichtige aus Sicht der
+Präsentation ist überhaupt einen Bug-Tracker zu
+<emphasis>haben</emphasis> und sicher zu stellen, dass er auf der
+Hauptseite sichtbar ist.</para>
</sect2>
@@ -653,42 +650,40 @@
<sect2 id="communications-channels">
<title>Kommunikationsewege</title>
-<para>Besucher wollen für gewöhnlich wissen, wie sie die Menschen die
-mit dem Projekt involviert sind erreichen können. Stellen Sie die
-Addressen von Mailing Listen, Chat Räumen, IRC Kanälen und andere
-Foren von Leuten die mit der Software zu tun haben erreicht werden
-können. Stellen Sie klar, dass Sie und die anderen Autoren des
-Projekts auf diese Listen eingetragen sind, damit Leute sehen können,
-dass es eine Möglichkeit gibt, an die Entwickler Rückmeldungen geben
-zu können. Ihre Anwesenheit auf den Mailing Listen impliziert nicht
-eine Verpflichtung auf alle Fragen zu antworten oder alle Anfragen
-für neue Funktionen zu implementieren. Auf lange Sicht, werden die
-Meisten eh niemals diesen Foren beitreten aber sie werden Trost darin
-finden, zu wissen, dass sie es <emphasis>könnten</emphasis> wenn es
-nötig sein sollte.</para>
-
-<para>In den frühen Abschnitten eines Projekts, gibt es keinen Grund
-Nutzer und Entwickler Foren zu trennen. Es ist viel besser jeden mit
-der mit der Software zu tun hat, zusammen in einem "Raum" reden zu
-haben. Unter den Personen die sich früh an einem Projekt beteiligen,
-ist die Unterscheidung zwischen Entwickler und Nutzer oft unscharf.
-Sofern die Unterscheidung gemacht werden kann, ist das Verhältnis
-von Entwickler zu Nutzern für gewöhnlich wesentlich höher in den
-frühen Tagen als später. Obwohl Sie nicht annehmen können, dass
-jeder der sich früh für das Projekt interessiert ein Programmierer
-der an der Software hacken will ist, können Sie annehmen, dass sie
-zumindest daran interessiert sind die Diskussionen um die Entwicklung
-mit zu verfolgen und ein Gefühl für die Richtung des Projekts zu
-bekommen.</para>
+<para>Besucher wollen oft wissen, wie sie die Menschen hinter dem
+Projekt erreichen können. Stellen Sie die Addressen der E-Mail
+Verteiler, Chat Räume, IRC Kanäle und andere Foren von Leuten die mit
+der Software zu tun haben erreicht werden können. Stellen Sie klar,
+dass Sie und die anderen Autoren des Projekts auf diese Verteiler
+eingetragen sind, damit Leute sehen können, dass es eine Möglichkeit
+gibt an die Entwickler Rückmeldungen zu geben. Ihre Anwesenheit auf den
+E-Mail Verteilern impliziert keine Verpflichtung auf alle Fragen zu
+beantworten oder alle Anfragen für neue Funktionen zu implementieren.
+Auf lange Sicht, werden die Meisten sowieso niemals diesen Foren
+betreten aber es wird sie Trösten, dass sie es
+<emphasis>könnten</emphasis> falls es werden sollte.</para>
+
+<para>Am Anfang eines Projekts, hat es keinen Sinn die Foren für Nutzer
+und Entwickler getrennt zu halten. Es ist viel besser alle die mit der
+Software zu tun haben, zusammen in einem "Raum" reden zu lassen. Unter
+den Personen die sich früh an einem Projekt beteiligen, ist die
+Unterscheidung zwischen Entwickler und Nutzer oft verwaschen. Sofern
+sie überhaupt gemacht werden kann, ist das Verhältnis von Entwickler zu
+Nutzern meißtens wesentlich höher in den frühen Tagen als später.
+Obwohl Sie nicht annehmen können, dass jeder der sich früh für das
+Projekt interessiert ein Programmierer ist, der an der Software hacken
+will, können Sie annehmen, dass sie zumindest daran interessiert sind
+die Diskussionen um die Entwicklung mitzuverfolgen und ein Gefühl für
+die Richtung des Projekts zu bekommen.</para>
-<para>Da es in diesem Kapitel nur darum geht ein Projekt ins laufen zu
-bringen, genügt es zu sagen, dass diese Kommunikations Foren existieren
-sollten. Später, in <xref linkend="growth"/><phrase output="printed"> und
-<xref linkend="communications"/></phrase>, werden wir untersuchten,
-wo und wie man diese Foren aufsteckt, in wie fern Sie unter Umständen
-Moderation erfordern und wie man Nutzer von Entwickler Foren trennt,
-sobald die Zeit kommt, ohne dabei einen unüberwindlichen See
-entstehen zu lassen.</para>
+<para>Da dieses Kapitel sich nur darum dreht ein Projekt ins laufen zu
+bringen, reicht es zu sagen, dass diese Foren existieren sollten.
+Später, in <xref linkend="growth"/><phrase output="printed"> im Kapitel
+<xref linkend="communications"/></phrase>, werden wir untersuchten wo
+und wie man diese Foren aufbaut, inwiefern Sie möglicherweise
+Moderation erfordern und wie man Foren für Nutzer und Entwickler sobald
+es nötig wird, voneinander trennt ohne dabei einen unüberwindliches Meer
+zu erschaffen.</para>
</sect2>
@@ -696,50 +691,50 @@
<sect2 id="developer-guidelines">
<title>Richtlinien für Entwickler</title>
-<para>Wenn jemand darüber nachdenkt etwas zu einem Projekt bei zu
-tragen, wird sie sich nach Richtlinien für Entwickler umschauen.
-Diese sind nicht so sehr technisch, als viel mehr sozialer Natur:
-sie erklären, wie Entwickler mit einander, den Benutzern umgehen und
-letztendlich, wie Sachen erledigt werden.</para>
+<para>Wenn jemand darüber nachdenkt etwas zu einem Projekt beizutragen,
+wird sie sich nach Richtlinien für Entwickler umschauen. Diese sind
+nicht so sehr technischer, als viel mehr sozialer Natur: Sie erklären,
+wie Entwickler miteinander und Benutzern umgehen und im wesentlichen,
+wie die Entwicklung gehandhabt wird.</para>
<para>Dieses Thema wird ausführlich in
-<xref linkend="written-rules"/><phrase output="printed"> und
-<xref linkend="social-infrastructure"/></phrase> behandelt, aber
-die Grundelemente dieser Richtlinien sind folgende:
+<xref linkend="written-rules"/><phrase output="printed"> im Kapitel
+<xref linkend="social-infrastructure"/></phrase> behandelt, aber die
+wesentlichen Elemente dieser Richtlinien sind folgende:
<itemizedlist>
- <listitem><para>hinweise auf Foren für die Zusammenarbeit mit
- Entwickler</para>
+ <listitem><para>Verweise auf Foren für die Zusammenarbeit mit
+ Entwickler.</para>
</listitem>
- <listitem><para>Anweisungen wie Bugs gemeldet und Patches abgegeben
- werden sollen.</para>
+ <listitem><para>Anleitungen wie man Fehler meldet und Patches
+ einreicht.</para>
</listitem>
- <listitem><para>irgend eine Andeutung darauf <emphasis>wie
- </emphasis> die Entwicklung für gewöhnlich abläuft-
- ist das Projekt eine wohlwollende Diktatur, eine
- Demokratie oder etwas anderes.</para>
+ <listitem><para>Irgend eine Hinweis darauf <emphasis>wie</emphasis>
+ die Entwicklung für gewöhnlich abläuft—ob das Projekt
+ eine gütige Diktatur, eine Demokratie oder etwas anderes
+ ist.</para>
</listitem>
</itemizedlist>
-Im übrigen soll "Diktatur" in keiner weise herabsetzend wirken. Es
-ist völlig in Ordnung eine Tyrannei zu betreiben, bei dem ein
-bestimmter Entwickler ein Recht auf Einspruch über alle Änderungen hat.
-Viele erfolgreiche Projekte funktionieren auf diese weise. Wichtig
-dabei ist nur, dass das Projekt es von vornherein klar macht. Eine
-Tyrannei die vorgibt eine Demokratie zu sein, wird Menschen abschrecken;
-eine Tyrannei die sagt, dass sie eine ist, wird zurecht kommen, sofern
-der Tyrann kompetent ist und vertraut wird.</para>
+Im übrigen soll "Diktatur" in keiner weise herabsetzend wirken. Es ist
+völlig in Ordnung eine Tyrannei zu betreiben, bei dem ein bestimmter
+Entwickler das letzte Wort über alle Änderungen haben kann. Viele
+erfolgreiche Projekte funktionieren nach diesem Modell. Wichtig dabei
+ist nur, dass das Projekt es von vornherein klar macht. Eine Tyrannei
+die vorgibt eine Demokratie zu sein, wird Menschen abschrecken; eine
+Tyrannei die klar sagt was sie ist, wird zurecht kommen sofern der
+Tyrann kompetent und vertrauenswürdig ist.</para>
-<para>Siehe <ulink
url="http://svn.collab.net/repos/svn/trunk/www/hacking.html"/>
-für ein Beispiel besonders gründlicher Entwickler Richtlinien oder
+<para>Siehe
+<ulink url="http://svn.collab.net/repos/svn/trunk/www/hacking.html"/>
+für ein Beispiel besonders gründlicher Richtlinien für Entwickler oder
<ulink url="http://www.openoffice.org/dev_docs/guidelines.html"/> für
allgemeinere Richtlinien die sich mehr auf die Steuerung und Teilnahme
-am Projekt konzentrieren, und weniger auf technische Angelegenheiten.
-</para>
+am Projekt als auf technische Angelegenheiten konzentrieren.</para>
-<para>Die separate Angelegenheit eine Einführung für Programmierer zur
-Verfügung zu stellen, wird in <xref
-linkend="developer-documentation"/><phrase output="printed">
+<para>Eine andere Angelegenheit eine Einführung für Programmierer
+bereitzustellen, wird in
+<xref linkend="developer-documentation"/><phrase output="printed">
später in diesem Kapitel behandelt</phrase>.</para>
</sect2>
@@ -748,176 +743,176 @@
<sect2 id="documentation">
<title>Dokumentation</title>
-<para>Dokumentation ist unerlässlich. Es muss <emphasis>irgend etwas
-</emphasis> für Leute zum lesen geben, selbst wenn es nur rudimentär
-und unvollständig ist. Dies fällt voll und ganz in die vorhin erwähnte
-Kategorie der "Plackerei" und ist oft der erste Bereich in der ein
-neues Open Source Projekt kurz fällt. Die Missionsziele und Funktions
-Liste zu formulieren, eine Lizenz zu wählen, den Entwicklungsstand
-zusammen zu fassen-sind alle relativ kleine Aufgaben, die endgültig
-erledigt werden können und es für gewöhnlich nicht erfordern erneut
-drüber zu gehen, sobald sie erledigt sind. Die Dokumentation hingegen,
-ist nie wirklich fertig, was vielleicht eine der Gründe ist, weshalb
-man es überhaupt anzufangen manchmal hinauszögert.</para>
-
-<para>Das heimtückischste ist, dass der Nutzen der Dokumentation für
-diejenigen die sie schreiben ist umgekehrt zu dem Nutzen, für neue
-Benutzer die sie lesen werden. Die wichtigste Dokumentation für neue
-Benutzer sind die Grundlagen: wie richte ich schnell die Software ein,
-eine Übersicht wie sie funktioniert, vielleicht auch Anleitungen für
-häufige Aufgaben. Diese Sachen sind jedoch genau solche, die den
-<emphasis>Autoren</emphasis> der Dokumentation nur all zu bekannt
-sind-so bekannt, dass es für sie schwierig sein kann sich in die Lage
-des Lesers hinein zu versetzen und mühselig die Einzelschritte
-die (für die Autoren) so offensichtlich erscheinen, dass sie kaum
-der Erwähnung wert sind.</para>
-
-<para>Es gibt keine magisch Lösung zu diesem Problem. Es muss sich nur
-jemand die Zeit nehmen sich hinzusetzen, sie auf zu schreiben und es
-anschließend an neue Nutzer auszuprobieren, um seine Qualität zu
-überprüfen. Benutzen Sie ein einfaches, leicht zu bearbeitendes
-Format wie HTML, Klartext oder eine XML variante-etwas, was für
-leichte schnelle und spontane Verbesserungen bequem ist. Was nicht
-nur zur Reduzierung des Mehraufwands, für die ursprünglichen Autoren,
-die Dokumentation schrittweise zu verbessern, sondern auch für
-diejenigen die später zum Projekt dazu kommen und an ihr arbeiten
+<para>Eine Dokumentation ist unerlässlich. Leute müssen <emphasis>irgend
+etwas</emphasis> zum lesen haben, selbst wenn es nur rudimentär und
+unvollständig ist. Sie fällt voll und ganz in die vorhin erwähnte
+Kategorie der "Plackerei" und ist oft der erste Bereich der in einem
+neuen Open Source Projekt zu kurz kommt. Die Missionsziele und Liste
+von Funktionen zu schreiben, die Wahl einer Lizenz, den
+Entwicklungsstand zusammenzufassen—das sind alles relativ kleine
+Aufgaben, die mit einem Schlag erledigt werden können und wenn sie
+erledigt sind, man muss sich normalerweise kein zweites Mal damit
+beschäftigen. Die Dokumentation hingegen ist nie wirklich fertig, was
+vielleicht eine Grund ist, dass man es manchmal hinauszögert sie
+überhaupt anzufangen.</para>
+
+<para>Das heimtückischste daran ist, dass der Nutzen einer Dokumentation
+für seine Autoren umgekehrt proportional ist zu dem für seine Leser, die
+neuen Benutzer. Die wichtigste Dokumentation für neue Benutzer sind die
+Grundlagen: Wie richte ich schnell die Software ein, eine Übersicht wie
+sie funktioniert, vielleicht auch Anleitungen für häufige Aufgaben.
+Diese Sachen sind jedoch genau solche, die den
+<emphasis>Autoren</emphasis> der Dokumentation nur allzu bekannt
+sind—so bekannt, dass es für sie schwierig sein kann sich in die
+Lage der Leser zu versetzen und mühselig die (für die Autoren)
+offensichtlichen Einzelschritte zu buchstabieren, die kaum einer
+Erwähnung wert erscheinen.</para>
+
+<para>Es gibt keine magisch Lösung für dieses Problem. Es muss sich nur
+jemand die Zeit nehmen sich hinzusetzen, sie aufzuschreiben und
+anschließend an neue Nutzer auszuprobieren um ihre Qualität zu
+überprüfen. Benutzen Sie ein einfaches, leicht zu bearbeitendes Format
+wie HTML, Klartext oder eine XML variante—etwas geeignetes für
+kleine und spontane Verbesserungen. Was nicht nur für die ersten Autoren
+den Mehraufwand reduziert die Dokumentation schrittweise zu verbessern,
+sondern auch für alle die später zum Projekt kommen und an ihr arbeiten
wollen.</para>
-<para>Eine Methode sicherzustellen, dass die erste Dokumentation der
-Grundlagen erledigt wird, ist von vorne herein seinen Umfang
-einzuschränken. So wird es sich zumindest nicht nach einer endlosen
-Aufgabe anfühlen. Eine gute Faustregel ist, dass es folgende minimale
-Bedingungen erfüllen sollte:</para>
+<para>Eine Weg sicherzustellen, dass eine erste Dokumentation der
+Grundlagen gemacht wird, ist von vornherein seinen Umfang zu begrenzen.
+So erscheint es zumindest nicht wie eine endlosen Aufgabe. Eine gute
+Faustregel ist, dass sie folgende minimale Bedingungen erfüllen
+sollte:</para>
<itemizedlist>
<listitem><para>Sagen Sie dem Leser klar wie viel technische
- Kenntnis von ihnen erwartet wird.</para>
+ Kenntnisse von ihm erwartet wird.</para>
</listitem>
<listitem><para>Beschreiben sie klar und deutlich, wie man die
- Software einrichtet und irgendwo am Anfang der Dokumentation,
- sagen Sie den Benutzern wie sie irgend eine Art Diagnose oder
- einfachen Befehl ausführen können, um zu bestätigen, dass sie
- es auch richtig eingerichtet ist. Die Dokumentation zum Anfang
- ist in mancherlei Hinsicht wichtiger als, die echte
- Bedienungsanleitung. Je mehr mühe jemand in die Installation
- und Einrichtung der Software investiert hat, desto
- beharrlicher wird sie dabei sein, fortgeschrittene Funktionen
- die nicht gut Dokumentiert sind, heraus zu finden. Wenn die
- Leute aufgeben, dann geben sie früh auf; deshalb sind es die
- frühsten Phasen, wie die Installation, welche die meiste
- Unterstützung brauchen.</para>
+ Software einrichtet und sagen Sie dem Benutzer irgendwo am
+ Anfang der Dokumentation woran man erkennet oder einen
+ einfachen Befehl der ihm sagt, ob sie auch richtig
+ eingerichtet wurde. Die erste Dokumentation ist in
+ mancherlei Hinsicht wichtiger als eine echte
+ Bedienungsanleitung. Je mehr mühe jemand in die
+ Installation und Einrichtung der Software investiert hat,
+ desto beharrlicher wird sie bleiben fortgeschrittene,
+ nicht gut dokumentierte, Funktionen herauszufinden. Wenn
+ Leute aufgeben, passiert es meistens gleich am Anfang;
+ deshalb sind es die frühsten Phasen, wie die Installation
+ bei der man die meiste Unterstützung braucht.</para>
</listitem>
- <listitem><para>Geben sie ein Lehrhaftes Beispiel einer häufigen
- Aufgabe. Offensichtlich wären viele Beispiele für viele
- Aufgaben noch besser, wenn aber die Zeit knapp ist, wählen
- Sie einen aus und geben Sie eine ausführliche Anleitung.
- Sobald jemand sieht, dass die Software für eine Sache benutzt
- werden <emphasis>kann</emphasis>, werden sie alleine anfangen
- herauszufinden was es noch kann-und mit etwas Glück, selber
- damit anfangen damit anfangen die Dokumentation auszufüllen.
- Was uns zum nächsten Punkt bringt...</para>
+ <listitem><para>Geben Sie ein lehrhaftes Beispiel einer häufigen
+ Aufgabe. Offensichtlich wären viele Beispiele für viele
+ Aufgaben noch besser, wenn die Zeit aber knapp ist, suchen
+ Sie sich eins aus und schreiben Sie eine ausführliche
+ Anleitung. Sobald jemand sieht, dass die Software für eine
+ Sache benutzt werden <emphasis>kann</emphasis>, werden sie
+ alleine anfangen herauszufinden was es noch kann—und
+ mit etwas Glück, selber damit anfangen die Dokumentation
+ zu erweitern. Was uns zum nächsten Punkt bringt...</para>
</listitem>
- <listitem><para>Kennzeichnen Sie Bereiche, bei denen die
- Dokumentation unvollständig ist. Indem sie den Lesern zeigen,
- dass Sie sich über die Defizite im klaren sind, stellen sie
- sich auf ihre Sichtweise ein. Ihr Einfühlungsvermögen,
- sichert ihnen zu, dass sie dass Projekt nicht davon überzeugen
- müssen was wichtig ist. Diese Kennzeichen, müssen keine
- Versprechungen die Lücken bis zu irgend einem bestimmten Datum
- aus zu füllen, repräsentieren - es ist genau so legitim sie als
- offenen Anfragen für die Hilfe von Freiwilligen zu behandeln.
- </para>
+ <listitem><para>Kennzeichnen Sie Bereiche der Dokumentation die
+ unvollständig sind. Indem Sie dem Leser zeigen, dass Sie
+ sich über die Defizite im klaren sind, stellen Sie sich auf
+ die Sicht der Leser ein. Ihr Einfühlungsvermögen sichert
+ ihnen zu, dass das Projekt nicht erst überzeugt werden muss
+ was wichtig ist. Diese Hinweise müssen keine Versprechen
+ repräsentieren die Lücken bis zu irgend einem bestimmten
+ Datum auszufüllen—es ist genau so legitim sie als
+ offenen Anfragen an die Hilfe der Freiwilligen zu
+ behandeln.</para>
</listitem>
</itemizedlist>
-<para>Der letzt Punkt ist von größerer Bedeutung und kann auf das
-ganze Projekt angewandt werden, nicht nur auf die Dokumentation.
-Eine genaue Buchführung bekannter Defizite ist in der Open Source
-Welt die Norm. Sie müssen die Mängel des Projekts nicht hochspielen,
-ermitteln Sie sie einfach nur gewissenhaft und Leidenschaftslos
-sobald es die Zeit erfordert (ob in der Dokumentation, auf dem
-Bug Tracker oder in einer Diskussion einer Mailing Liste). Keiner
-wird dies wie Miesmacherei seitens des Projekts behandeln, noch
-als Verpflichtung die Probleme bis zu einem bestimmten Datum zu
-lösen, es sei denn das Projekt macht explizit eine solche
-Verpflichtung. Da jeder der die Software benutzt, diese Mängel
-selbst finden wird, ist es besser für sie psychologisch darauf
-vorbereitet zu sein-so wird es danach aussehen, als ob das Projekt
-eine solide Kenntnis davon hat, wie es läuft.</para>
+<para>Der letzt Punkt ist von größerer Bedeutung und kann auf das ganze
+Projekt angewandt werden, nicht nur auf die Dokumentation. Eine genaue
+Buchführung über bekannte Defizite ist in der Open Source Welt die
+Norm. Sie müssen die Mängel des Projekts nicht hochspielen, sondern
+einfach gewissenhaft und leidenschaftslos ermitteln, sobald es dafür
+Zeit wird (ob in der Dokumentation, auf dem Bug-Tracker oder in einer
+Diskussion auf einem Verteiler). Keiner das als von dem Projekt
+ausgehende Miesmacherei behandeln, noch als Verpflichtung die Probleme
+bis zu einem bestimmten Datum zu lösen, es sei denn das Projekt geht
+explizit eine solche Verpflichtung ein. Da jeder der die Software
+benutzt diese Mängel selbst finden wird, ist es besser für sie
+psychologisch darauf vorbereitet zu sein—so wird es aussehen als
+ob das Projekt genau über seinen Zustand bescheid weis.</para>
<sidebar id="starting-a-faq">
- <title>Eine FAQ Pflegen</title>
+ <title>Die Pflege einer FAQ</title>
- <para>Eine <firstterm>FAQ</firstterm> ("Frequently Asked Questions"
- /Häufig gestellte Fragen Dokument)kann einer der besten Investitionen
- sein, die ein Projekt machen kann, auf Grund der Rückzahlung in Form
- von Bildung. FAQs sind sehr auf Fragen abgestimmt, die von Benutzern
- und Entwickler tatsächlich gefragt werden-im Gegensatz zu Fragen die
- Sie vielleicht von ihnen <emphasis>erwartet</emphasis> hätten- und
- deshalb neigt eine gut gepflegte FAQ dazu, denjenigen die sie
- zu rate ziehen, genau das zu geben wonach sie suchen. Die FAQ ist
- oft die erste Stelle die Benutzer durchsuchen, wenn sie über ein
- Problem laufen, oft geben sie es sogar dem offiziellen Handbuch den
- Vorzug und es ist wahrscheinlich das Dokument in ihrem Projekt
- welches am wahrscheinlichsten von anderen Seiten verlinkt wird.</para>
+ <para>Eine <firstterm>FAQ</firstterm> ("Frequently Asked
+ Questions"<footnote><para>Häufig gestellte Fragen</para></footnote>)
+ kann, aufgrund seiner Auszahlung in Form von Aufklärung, einer der
+ besten Investitionen sein die ein Projekt machet. Eine FAQ ist sehr
+ auf Fragen abgestimmt, die von Benutzern und Entwickler wirglich
+ gestellt werden—nicht auf Fragen die Sie vielleicht von ihnen
+ <emphasis>erwarten</emphasis> würden—und deshalb neigt eine gut
+ gepflegte FAQ dazu, denjenigen die sie zu rate ziehen, genau das zu
+ geben, wonach sie suchen. Die FAQ ist oft die erste Stelle die
+ Benutzer durchsuchen, wenn sie auf ein Problem stoßen, sie ziehen es
+ sogar oft dem offiziellen Handbuch vor und es ist wahrscheinlich das
+ Dokument in ihrem Projekt, worauf anderen Seiten am ehesten
+ verweisen.</para>
<para>Leider können Sie die FAQ nicht am Anfang eines Projekts
- schreiben. Eine gute FAQ wird nicht geschrieben, sie wird gewachsen.
- Sie sind per Definition reaktive Dokumente, die sich im laufe der
- Zeit auf Grund der täglichen Nutzung der Software, entwickeln. Da es
- unmöglich ist die Fragen die von Nutzern gestellt werden voraus zu
- sehen, ist es unmöglich sich hinzusetzen und von Grund auf eine
+ schreiben. Eine gute FAQ schreibt man nicht, man lässt sie wachsen.
+ Sie sind schon nach ihrer Definition auf Rückmeldung angewiesene
+ Dokumente, die sich mit der Zeit durch die täglichen Nutzung der
+ Software entwickeln. Da es unmöglich ist die Fragen der Benutzer zu
+ erahnen, ist es unmöglich sich hinzusetzen und von Grund auf eine
nützliche FAQ zu schreiben.</para>
- <para>Verschwenden Sie also nicht ihre Zeit dabei es zu versuchen.
- Sie können jedoch ein größtenteils leere FAQ Vorlage aufstellen,
- damit es einen offensichtlichen Ort gibt zu dem Leute Fragen und
- Antworten beitragen können, nachdem das Projekt auf dem Weg gebracht
- ist. In dieser Phase ist die wichtigste Eigenschaft nicht
- Vollständigkeit, sondern Bequemlichkeit: Wenn das Hinzufügen einfach
- ist, werden Leute zu ihr hinzufügen. (Die vernünftige Pflege einer
- FAQ ist ein nicht triviale und faszinierendes Problem welches weiter
- in <xref linkend="faq-manager"/><phrase output="printed"> im Kapitel
- <xref linkend="managing-volunteers"/></phrase> behandelt wird.)</para>
+ <para>Verschwenden Sie also nicht Ihre Zeit dabei es zu versuchen.
+ Sie können jedoch eine größtenteils leere FAQ einrichten, als Vorlage
+ und offensichtlichen Ort an dem Leute Fragen und Antworten eintragen
+ können, sobald das Projekt läuft. Zunächst ist ihre wichtigste
+ Eigenschaft aber nicht ihre Vollständigkeit, sondern ihre
+ Bequemlichkeit: Wenn es einfach ist neue Einträge zu machen, werden
+ Leute es auch machen. (Die vernünftige Pflege einer FAQ ist ein nicht
+ ganz triviale aber faszinierende Angelegenheit die in
+ <xref linkend="faq-manager"/><phrase output="printed"> im Kapitel
+ <xref linkend="managing-volunteers"/></phrase> weiter behandelt
+ wird.)</para>
</sidebar>
<sect3 id="documentation-availability">
-<title>Verfügbarkeit der Dokumentation</title>
+<title>Erreichbarkeit der Dokumentation</title>
-<para>Die Dokumentation sollte von zwei Quellen verfügbar sein:
-Online (direkt von der Webseite), <emphasis>und</emphasis> in der
-herunterladbaren Version der Software (siehe <xref
-linkend="packaging"/><phrase output="printed"> im Kapitel
-<xref linkend="development-cycle"/></phrase>). Es muss online sein,
-in einer durchsehbaren Form, da Leute die Dokumentation oft
-<emphasis>vor</emphasis> sie die Software zum ersten Mal
-herunterladen lesen um besser entscheiden zu können, ob sie es
-überhaupt herunterladen sollen. Es sollte aber auch der Software bei
-liegen, auf Grund des Prinzips, dass ein heruntergeladenes Paket,
-alles enthalten sollte(lokal verfügbar machen sollte), was man
-benötigt um die Software zu benutzen.</para>
-
-<para>Stellen Sie sicher, dass ein Link verfügbar ist, der zur
-<emphasis>ganzen</emphasis> online Dokumentation in einem HTML
-Dokument führt(schreiben Sie einen Hinweis wie "monolitisch" oder
-"eine einzige große Datei" haben, damit die Leser wissen, dass es
-eine weile brauchen kann zu laden). Das ist deshalb nützlich, da
-Leute oft die ganze Dokumentation nach einem bestimmten Wort
-durchsuchen wollen. Im allgemeinen wissen sie, schon wonach sie
-suchen, können sich aber nur nicht daran erinnern in welchem
-Abschnitt es ist. Für solche Leute, gibt es nichts frustrierenderes
-als einer HTML Seite für die Inhaltsangabe, einer für die Einleitung,
-noch eine weitere für die Installationsanleitung, usw. zu begegnen.
-Wenn die Seiten auf diese Art aufgebrochen sind, ist die such Funktion
-ihres Browsers nutzlos. Der aufgeteilte Stil, ist nützlich für
-diejenigen, die schon wissen welchen Abschnitt sie brauchen oder
-die ganze Dokumentation von vorne bis hinten durchlesen wollen. Das
-ist aber <emphasis>nicht</emphasis> die häufigste Art auf dem auf die
-Dokumentation zugegriffen wird. Viel häufiger, kennt sich jemand
-im Grunde genommen mit der Software aus und kehrt zurück um nach
-einem bestimmten Wort oder Ausdruck zu suchen. Ihnen keine
-monolitische Datei zur Verfügung zu stellen, würde ihnen nur das
-Leben schwerer machen.</para>
+<para>Die Dokumentation sollte an zwei Stellen erreichbar sein: Online
+(direkt von der Webseite) <emphasis>und</emphasis> in der
+veröffentlichten Version der Software (siehe
+<xref linkend="packaging"/><phrase output="printed"> im Kapitel
+<xref linkend="development-cycle"/></phrase>). Man muss sie online
+durchsuchen können, da Leute die Dokumentation oft lesen wollen
+<emphasis>bevor</emphasis> sie die Software zum ersten Mal
+herunterladen, um besser entscheiden zu können, ob sie es überhaupt
+herunterladen sollen. Es sollte aber auch der Software bei liegen,
+aufgrund des Prinzips, dass ein veröffentlichtes Paket, alles enthalten
+sollte(d.h. lokal verfügbar machen sollte), was nötigt ist um die
+Software zu benutzen.</para>
+
+<para>Es sollte unbedingt einen Link geben der auf die
+<emphasis>komplette</emphasis> Dokumentation in einer einzigen HTML
+Datei verweist (schreiben Sie einen Hinweis wie "monolitisch" oder
+"eine einzige riesige Datei" daneben, damit Leser nicht überrascht sind
+wenn es beim laden etwas Zeit braucht). Das ist nützlich, da Leute oft
+die ganze Dokumentation nach einem bestimmten Wort durchsuchen wollen.
+Im allgemeinen wissen sie, schon wonach sie suchen und können sich nur
+nicht daran erinnern in welchem Abschnitt es ist. Für solche Leute,
+gibt es nichts frustrierenderes als eine HTML Seite für die
+Inhaltsangabe, einer für die Einleitung, eine weitere für die
+Installationsanleitung, usw. Wenn die Seiten auf diese Art aufgebrochen
+sind, ist die Suchfunktion ihres Browsers nutzlos. Eine in mehrere
+Seiten Aufgebrochene Dokumentation ist für Personen nützlich, die schon
+wissen welchen Abschnitt sie brauchen oder die ganze Dokumentation von
+vorne bis hinten durchlesen wollen. Das ist aber
+<emphasis>nicht</emphasis> die häufigste Art auf die Dokumentation
+zuzugegreifen. Viel häufiger, kennt sich jemand im Grunde genommen mit
+der Software aus und kehrt zurück um nach einem bestimmten Wort oder
+Ausdruck zu suchen. Keine monolitische Datei bereitzustellen, würde das
+Leben nur erschweren.</para>
</sect3>
_______________________________________________
Producingoss-translators mailing list
[email protected]
http://www.red-bean.com/mailman/listinfo/producingoss-translators
