Zuerst freigeben oder zuerst dokumentieren?

23

Ich arbeite jetzt seit ein paar Jahren an einem Projekt und beginne, eine anständige Nutzerbasis aufzubauen. Ich habe eine Projektseite mit einigen grundlegenden Dokumentationen erstellt, aber es ist derzeit nicht viel mehr als eine FAQ. Ich weiß, dass ich es verbessern muss, damit es sowohl für neue als auch für erfahrene Benutzer informativer ist, und das steht als nächstes auf meiner To-Do-Liste für die nächste Version.

Die nächste Version bietet jedoch Funktionen, auf die die Anwenderbasis sehr gespannt ist. Ich bin jetzt bereit, es zu veröffentlichen, es ist verpackt und bereit zu gehen. Ich muss es nur für die entsprechenden Verteilungsdienste bereitstellen.

Auf den Punkt gebracht. Die Funktionen sind für meine Benutzer wichtig, aber die Dokumentation ist für mich wichtig. Soll ich mit der Veröffentlichung warten, bis ich die Dokumentation neu geschrieben habe? Meine derzeitige Nutzerbasis ist geschickt genug, um zu verstehen, wie man die neuen Funktionen verwendet, weshalb ich mir keine Sorgen mache. Es kann ein paar Wochen dauern, bis die Dokumente fertig sind, da ich nur wenig Zeit habe, um an diesem Projekt zu arbeiten, aber die Community würde mich am Spieß rösten, wenn ich sie länger warten lassen würde.

Ist der Kunde in diesem Szenario richtig? Sollte eine fantastische, unkomplizierte Funktion für bestehende Benutzer Vorrang vor zuverlässiger Dokumentation für neue Benutzer haben?


Update: Wow, so viele großartige, qualitativ hochwertige Antworten! Sie haben mir wirklich geholfen, besser zu verstehen, wie ich das Projekt und seine Benutzer interagieren und unterstützen sollte. Tausend Dank!

Cyberbit
quelle
14
Ja, der Kunde hat recht. Stellen Sie die Veröffentlichung bereit und verbringen Sie dann die zwei Wochen damit, die Dokumentation zu erstellen. Sie haben uns bereits mitgeteilt, dass die Anwenderbasis durch den Mangel an Dokumentation nicht beeinträchtigt wird und es nur noch zwei Wochen sind. Wenn dies ein echter Auftritt wäre, würde Ihr Kunde oder Ihre Organisation Sie auf die Probe stellen, denn zwei Wochen ohne Veröffentlichung sind zwei Wochen weniger, um Marktanteile zu gewinnen.
Robert Harvey
3
Je nach Projekt können Sie die neue Version in einem separaten Zweig als "Beta" oder "Vorschau" veröffentlichen.
CodesInChaos
2
Welche Art von Dokumentation - Endbenutzerdokumentation oder Quellcodedokumentation? Oder handelt es sich bei Ihrem Projekt um ein Projekt, bei dem zwischen diesen kein Unterschied besteht?
Doc Brown
5
Hier scheint es keinen Konflikt zu geben: Wenn es gepackt und einsatzbereit ist, warum können Sie es dann nicht freigeben und in zwei Wochen an der Dokumentation für ein Nur-Dokument-Update arbeiten? Befürchten Sie, dass die Veröffentlichung eine Menge Arbeit (bei gemeldeten Fehlern usw.) verursacht, die Sie daran hindert, an den Dokumenten zu arbeiten? Der Grund, warum Sie nicht beides können, sollte durch Antworten berücksichtigt werden.
Steve Jessop
@DocBrown In diesem Fall ist es Benutzerdokumentation. Quellcode-Dokumentation wäre nur für mich nützlich.
Cyberbit

Antworten:

45

Ganz einfach: Geben Sie eine Beta-Version frei! Wenn die Dokumentation fertig ist, führen Sie die endgültige Veröffentlichung der neuen Version durch.

Wenn Sie Benutzer haben, die bereit sind, das Neue auszuprobieren, dann nutzen Sie dies auf jeden Fall. Sie erhalten Fehlerberichte, erhalten wahrscheinlich Community-Fragen zu den schwierigen Punkten, damit Sie wissen, wo Sie sich auf die Dokumentation konzentrieren müssen usw. Möglicherweise möchten Sie auch einige Dinge auf der Grundlage von Benutzerfeedbacks optimieren, die sich auf die Dokumentation auswirken können.

Grundsätzlich gewinnt jeder.


Ein Grund, nicht vorzeitig zu veröffentlichen, ist, wenn Sie der Meinung sind, dass Ihre Benutzer keine "Beta-Version" erhalten, sollten Sie zweimal darüber nachdenken, aber was Sie schreiben, hört sich so an, als würden sie sich darüber freuen.

Ein weiterer Grund wäre, wenn es technische Schwierigkeiten gibt, ein Beta-Release über die von Ihnen verwendeten Release-Kanäle durchzuführen. Dann ist es möglicherweise umständlicher, separate Beta- und Endveröffentlichungen durchzuführen. Wenn Sie der Meinung sind, dass Ihre Software vollständig ist, würde ich mich in diesem Fall auf eine frühzeitige Veröffentlichung stützen und die Dokumentation aktualisieren, wenn dies abgeschlossen ist. Andernfalls besteht das Risiko, dass die Dokumentation verzögert wird und dann die gesamte Veröffentlichung verzögert wird oder Sie die Veröffentlichung ohnehin ohne endgültige Dokumentation beenden. Tun Sie dies jetzt.

hyde
quelle
1
Ich habe das in der Vergangenheit so oft für kleine Tools gemacht ... Code ist fertig, alles scheint zu funktionieren, aber es ist das Ende des Wochenendes und ich kann mich nicht die Mühe machen, die Dokumentation jetzt fertig zu stellen. Ich habe es nur als Beta-Version gepackt und voila, wenn du die neue Version dringend wolltest, dann ist es hier, sonst musst du auf das nächste Wochenende warten.
Pimgd
Ich habe tatsächlich über eine Beta-Version nachgedacht, bevor ich hier gefragt habe! Das Problem mit dieser Idee ist, dass die Kanäle, die ich benutze, mich zwingen, eine völlig separate App zu schreiben, um geteilte Releases zu haben. Ich habe angefangen, an einer separaten Beta zu arbeiten, aber die Logistik ist schwierig und es schien sich in dieser Phase des Projekts nicht gelohnt zu haben.
Cyberbit
Stattdessen habe ich mich dafür entschieden, es in einer normalen Version zu einer Opt-In-Beta zu machen. Auf diese Weise wird sichergestellt, dass Benutzer, die eine stabile Erfahrung wünschen, diese beibehalten und die Benutzer, die die neue Funktion wünschen, sie mit dem Wissen verwenden können, dass sie manchmal fehlerhaft ist. Dann kann ich in einer zukünftigen Version die Funktion von "Opt-In" auf "Integriert" umstellen, die Beta-Bezeichnung entfernen und alles ist in Ordnung in der Welt.
Cyberbit
3
Apache verwendet "Release Candidates", um ein Projekt zu kennzeichnen, das funktionsfähig ist, aber nur überprüft, ob das Paket alle Ressourcen enthält und wirklich für die Hauptsendezeit bereit ist. Klingt so, als ob Sie sich jenseits der Beta-Phase befinden (Funktionalität ausgereift, aber immer noch nicht vollständig).
Berin Loritsch
@BerinLoritsch Ich habe das schon mal gesehen. Das Etikett passt eigentlich gut in diesen Fall. Ich denke, ein Opt-In-Feature in eine normale Version zu integrieren, ist (in meinem Fall) so etwas wie ein Release-Kandidat. Es ist stabil, es funktioniert, aber es hat das Licht noch nicht gesehen.
Cyberbit
15

Wenn ich dich richtig verstanden habe, machst du dieses Projekt in deiner Freizeit und ohne Geld . Wenn dies der Fall ist, tun Sie bitte, was Sie besser fühlen lässt (Benutzer warten, dokumentieren Ihre Zeit). Sie sollten den Druck Ihrer "Benutzer" nicht spüren. Viele Leute haben darüber im Internet geschrieben (große FLOSS-Autoren und -Beitragende, die den Druck verspürten).

Wenn Sie jedoch bezahlt werden oder einen Vorteil erhalten, tun Sie bitte, was Ihre Benutzer möchten. In diesem Fall müssen Sie nur das tun, was für Ihre Kunden oder Benutzer am besten ist. Geben Sie es frei und dokumentieren Sie Ihre Zeit. Sie sagten, sie würden sich zurechtfinden, also sollte es keine große Sache sein.

Pietromenna
quelle
Du hast es richtig! Dies ist ein unbezahlter Auftritt. Aber ich habe einige Vorteile, da ich einer der Hauptbenutzer bin, über die ich gesprochen habe. : P Was Sie sagen, macht Sinn, und ich weiß Ihre Antwort zu schätzen!
Cyberbit
4

Im Allgemeinen gibt es zwei Arten von Dokumentation: die technische Dokumentation Ihres Codes (Klassen, Einheiten usw.) und die Funktionsweise und Implementierung neuer Funktionen in der Code- und Benutzerdokumentation. IMO, technische Dokumentation ist ein Muss, besonders wenn die Softwareentwicklung nicht Ihre Vollzeitbeschäftigung ist. Ich verbringe viel Zeit damit, da ich möglicherweise aufgrund von lebenslangen Verpflichtungen große Lücken beim Schreiben von Code habe.

Benutzerdokumentation ist gut zu haben, aber ich glaube nicht wesentlich. Natürlich hängt es von der Komplexität der Anwendung, der Vertrautheit der Benutzer mit dem Einsatz von Computern und Systemen in dem diskutierten Themenbereich ab - in Ihrem Fall können Ihre Kunden sich ein Bild davon machen, wie neue Funktionen funktionieren. Es gibt eine Reihe von Überlegungen, wonach für eine gute Benutzererfahrung und eine gute Benutzeroberfläche nur minimale Benutzerdokumentation erforderlich ist.

Wenn Ihre Zeit begrenzt ist und Sie wirklich den Druck verspüren, die von Ihnen vorgeschlagene Dokumentation zu entwickeln, können Sie auch ein paar kurze Videos erstellen, in denen nur die neuen Funktionen vorgestellt werden. Dadurch haben Sie etwas Zeit, um die eigentliche Dokumentation zu schreiben, und können dann die weniger wichtigen Details eingeben.

Mit einigen Marketing-Tipps können Sie die Erwartungen der Nutzer in Einklang bringen und dennoch Ihre Marke stärken. Es hängt wirklich von der Art der Anwendung und dem Workflow ab, den Sie bisher erstellt haben. Sie können jedoch einen Begrüßungsbildschirm für Ihre neue Version anzeigen und die Videos in der Anwendung anzeigen, indem Sie Links bereitstellen oder die Videos in der App abspielen.

John Kouraklis
quelle
3

Nur um etwas hinzuzufügen, nicht nur für dieses spezielle Beispiel, sondern für den allgemeinen Workflow:

Dokumentation mag Ihre sein definition of done, aber Dokumentation ist die meiste Zeit jenseits eines Minimal-Viable-Produkts (MVP).

Der Kunde hat nicht nur immer Recht. Wenn es sich um ein kommerzielles Produkt handelt, ist die Freigabe möglicherweise von großem geschäftlichem Wert und hat absolute Priorität.

Der Eigentümer definiert den Geschäftswert (was ist Ihrer Meinung nach der Unternehmenswert). Was ist als Produkt für Ihre Kunden wertvoller?

Gibt es auch Risiken bei der Freigabe ohne Dokumentation?

Zum Beispiel Wettbewerb ; Wenn der Wettbewerb dieses Super-Feature vor Ihnen veröffentlicht, verlieren Sie möglicherweise einige Benutzer.

Stellen Sie sich oder dem Produktbesitzer diese Fragen und Ihre Antwort wird klar sein.

Timmetje
quelle
2

Neue Funktionen machen alte Benutzer glücklich. Gute Dokumentation lädt neue Benutzer ein. Worauf Sie sich konzentrieren sollten, hängt davon ab, was Sie mehr brauchen. Sie haben angegeben, dass die Benutzerbasis fehlerfrei ist, damit neue Funktionen warten können. Da ich als alter Benutzer spreche, mag ich auch eine gute Dokumentation. Das Schöne an Open Source: Alte Benutzer fügen ihre eigenen Funktionen hinzu.

kandierte_orange
quelle
2
Gute Dokumentation lädt neue Benutzer nur dann ein, wenn sie etwas dokumentiert, was tatsächlich existiert.
Robert Harvey
@robertharvey Es wurde eine aktuelle Benutzerbasis angegeben. Daher gehe ich davon aus, dass sie eine unveröffentlichte Beta verwenden.
candied_orange
Es gibt eine Veröffentlichung, die vom Sound her als stabil gilt, obwohl sie nicht ausreichend dokumentiert ist.
jpmc26
2

Sie haben in Ihrer Frage und wahrscheinlich auch Ihren Benutzern nicht die Konsequenzen dieser Entscheidungen geklärt. Wie viel Zeit investieren Sie in die Benutzerunterstützung? Verringert zusätzliche Dokumentation den Zeitaufwand für Support oder steigert sie den Umsatz? Was ist der Vorteil für Sie, um Dokumentation zu machen?

Ihre Benutzer möchten über die Dokumentation hinaus neue Funktionen, sind sich jedoch darüber im Klaren, dass Ihre Verfügbarkeit für die Bereitstellung von Support, die Behebung von Fehlern, die Veröffentlichung von Patches usw. möglicherweise abnimmt?

Wenn ich mir nicht die Mühe gemacht hätte, die Anweisungen zu lesen, sondern nur eine E-Mail mit meiner Frage an Sie gesendet hätte, warum sollte ich dann jemals eine Dokumentation über neue Funktionen wünschen?

JeffO
quelle
-1

Wenn das Paket zur Freigabe bereit ist, geben Sie es an den Kunden / Kunden weiter und beginnen Sie mit der Arbeit an der Dokumentation. Es empfiehlt sich, dem Client mitzuteilen, wann Sie die Dokumentation freigeben, um die bereitgestellten Funktionen besser zu verstehen.

sairamys
quelle