DDP Todo-Liste

Dringende Todo-Liste:

Rücksichtsloses Ernten fader Dokumentation
Löschen von nicht gewarteter Dokumentation (besser so?)
Vorschreiben einer Dokumentations-Hierarchie. Hauptsächlich die Dokumentations-Regeln vervollständigen, mit der Genehmigung und dem Segen des Web-Teams. Das beinhaltet konsistente Pfade im Web-Bereich und in den Paketen. Es gibt hier einen Entwurf, aber dieser muss erst überarbeitet werden.
Einrichten von Infrastruktur für mehrsprachige Dokumentation, um Übersetzern zu ermöglichen, direkt im CVS-Bereich zu arbeiten.
Einen Weg hinzufügen, um Übersetzungen automatisch zu betreuen, wie es auch mit den Website-WML-Quellen gemacht wird.
Festlegen, welche Informationen auf der CD enthalten sein sollen und eine Methode automatisieren, um einen ordentlichen Index zu erstellen. Relevante Informationen befinden sich hier und Subversion enthält einige Skripte, die poliert und einem Cron-Job hinzugefügt werden müssen.

Ideen:

Das Folgende ist nur eine Liste von Ideen, die in verschiedenen Threads auf unserer Mailingliste aufkamen. Sie können daher eine gute oder schlechte Idee sein. :-)

Bereitstellen einer konsistenten Schnittstelle zu allen Handbuchseiten in Debian, so wie es viele anderen wie FreeBSD, NetBSD, OpenBSD, HP (HPUX), IBM (AIX), SGI (Irix), und Sun (Solaris) bereits tun. Interessanterweise gibt es mehrere Server (wie Fifi), die bereits alle Handbuchseiten in Debian bereitstellen. Dies ist Fehler #264589. Es gab eine erste Betaversion auf manpages.debian.net, but diese ist derzeit nicht verfügbar.
Implementierung von URNs. Dadurch können Anwender lokal, auf der Website oder auf Spiegeln nach Dokumentation suchen. Lokale Konfiguration kann verwendet werden, um anzugeben, welche Spiegel näher liegen oder bequemer zu erreichen sind. doc-base kann URNs benutzen, um auf Dokumente zu zeigen anstatt auf Dateinamen.
Ich habe über Ausgabeformate nachgedacht, die wir in Debian-Paketen (.debs) verwenden möchten. Wir müssen HTML einbinden (das geben die Regeln vor), einige Leute möchten jedoch auch PostScript- oder Text-Versionen sehen. Daher hatte ich die Idee, nur den SGML-Quellcode zu verteilen und die gewünschten Ausgabeformate zur Laufzeit zu erzeugen (das kann während der Installation oder später geschehen). Das hätte verschiedene Vorteile:
- Die .debs wären klein
- Größtmögliche Flexibilität
- Wir könnten sogar die Links während des Kompilierens justieren, z.B. indem Internet-Links in lokale umgewandelt werden, wenn die Dateien vorhanden sind.
- Es ist wahrscheinlich einfacher, eine Index-Seite aktuell zu halten (á la dwww)
Ich sehe folgende Nachteile:
- Die Leute müssen debiandoc-sgml installiert haben (was jedoch nicht viel ist)
- Kompilieren wird ein paar Sekunden dauern (nicht zu lange, jedoch länger als einfaches Auspacken)
doc-base könnte die Grundlagen eines solchen Systems definieren, da es bereits Metadaten für Dokumente ordnet.
Ergründen, welche Dokumente von unseren Benutzern wirklich verwendet (oder gesucht) werden, so dass wir uns auf diese konzentrieren können. Dies ist etwas, was noch nicht untersucht wurde. Die Benutzer-Mailinglisten (Durchführen einer Umfrage), die Web-Log-Statistiken (sowohl der Haupt-WWW-Seite als auch der Spiegelserver) und, da Dokumente auch als Debian-Pakete vertrieben werden, die Daten des Beliebheitswettbewerbes könnten als Informationsquellen genutzt werden.
Erstellen der Information zu verfügbaren Handbüchern, die auf der Webseite präsentiert werden, indem die Info (welche von manual.defs und version.defs bereitgestellt wird) automatisch aus dem CVS bezogen wird.
Es ermöglichen, den Übersetzungsstatus basierend auf Informationen von der CVS-Seite zu verfolgen. Möglicherweise unter Wiederverwendung der Rahmensystems, wie es von debian-installer für das Installationshandbuch entwickelt wurde.
Verfolgen des last-changed-Status von Dokumenten, so dass Benutzer, die die verfügbaren Dokumente durchstöbern, feststellen können, ob das Dokument für sie von Bedeutung ist (oder nicht).
Überlegen, ob Dokumentation für Benutzer in nicht-englischer Sprache bereitgestellt werden soll (CVS enthält Verzeichnisse für einige Sprachen und etwas Dokumentation, welche ursprünglich in einer anderen als der englischen Sprache geschrieben wurde).
Überlegen, ob eine interaktive Einrichtung für Benutzer zum Kommentieren von Dokumenten durch eine Wiki-artige Schnittstelle bereitgestellt werden soll, getrennt von der Haupt-Darbietung der Webseite oder auf dieselbe Art dargeboten. Diese Rückmeldung könnte vom Autor genutzt werden, und, obgleich offen für Missbrauch, es hat recht gut bei anderen Dokumentationsprojekten (PHP) funktioniert.
Benutzer ein generisches Fehlerverfolgungssystem für Dokumentation verwenden lassen. Es wird für die Dokumente benutzt, die ein Paket bereitstellen, aber nicht alle Dokumente tun das.