Effektive Dokumentation für Discourse schreiben

[maiki]

Hallo Simon!

@simon

@Discourse

Verwenden Sie Kontraktionen: it’s, you’ll, you’re, we’re, let’s

Neben der Vermeidung von Idiomen habe ich auch immer die Verwendung von Kontraktionen in Dokumenten vermieden. Ich dachte, sie würden es für Nicht-Englisch-/Nicht-West-Leser schwerer verständlich machen. Englisch ist eine seltsame Sprache.

Ich wollte sehen, wie sich das entwickelt, aber ja, mir geht es genauso, ich versuche, Kontraktionen zu vermeiden.

@simon

@Discourse

Verwenden Sie Übergangswörter wie moreover, although, hence und therefore

moreover?

Hahaha, ja… Ich werde keines dieser Wörter in Dokumenten verwenden, damit ich nicht mein offenbare.

@simon

Es könnte sich lohnen, einen konsistenten Platzhalternamen zu verwenden, um sich auf Discourse-Sites zu beziehen. Vielleicht discourse.example.com? Es gibt hier einige Dokumentationen, die sich auf die Discourse-Site als sitename.com beziehen. Das hat mich wirklich verwirrt.

Definitiv: Example Domains

@simon

So sehr ich es schätze, nicht mehr eine Menge Dokumentationsthemen mir zugeschrieben zu bekommen, fühlt es sich ein wenig kalt an, Discourse als Autor aller Dokumentationsthemen des Teams zu verwenden.

Was das Schreiben für mich wieder unterhaltsam gemacht hat, war der Rat, Wege zu finden, ein wenig von sich selbst in das zu stecken, was man schreibt. Es könnte alles sein, Ihr Tonfall, Ihre Hobbys, was auch immer… Das ist irgendwie das Gegenteil von dem, was hier empfohlen wird.

Das ist der Punkt, den ich hier besprechen wollte!

Wir hatten viel hin und her darüber, und ich war froh zu sehen, dass dies standardmäßig in den Styleguide aufgenommen wurde.

Hier ist, warum ich es für wichtig halte: Die Erstellung von Dokumentationen muss für so viele Mitglieder unserer Community wie möglich zugänglich sein, einschließlich (insbesondere?) unserer Discourse-Teammitglieder.

Discourse ist eine soziale Diskussionssoftware. Und einige Dokumentationen sind wirklich eine fortlaufende Konversation. Wenn ich eine Praxis teile, wie ich Mitglieder in meiner Community anwerbe, möchte ich als „Besitzer“ dieses Themas präsentiert werden, damit ich Fragen beantworten und das Thema erweitern kann.

Auf der anderen Seite, wenn ein Kunde nach einer Funktion fragt, die wir nie erklärt haben, möchte ich den Styleguide verwenden und nützliche, allgemeine Dokumentationen erstellen können, was meiner Meinung nach die Veröffentlichung durch die Themenbesitzerschaft mehr Trägheit verleiht.

Außerdem, wenn wir Dokumentationen außerhalb von Discourse erstellen (eine Integration oder Erstellung aus Code-Kommentaren oder was auch immer), ist es wahrscheinlich einfacher, einen „Dokumentationsbenutzer“ als Implementierungsdetail zu haben.

Ich glaube nicht, dass dieser Leitfaden Leute davon abhalten wird, ihre Stimme und Persönlichkeit einzubringen und die Diskussion zu hosten. Aber es wäre großartig, wenn er mehr Leuten hilft, sich mit dem Dokumentieren zu beschäftigen, die es sonst nicht tun würden (und dann können wir sie anstupsen, persönlicher zu werden!)