README 80 Zeichen Grenze oder lassen Sie einfach den Benutzer-Editor behandeln?

Question

Ich bin mir sicher, dass viele Leute in beide Richtungen streiten werden und leider scheint es keine "offizielle Antwort" zu geben. Ein Teil von mir will nur schreiben und nicht auf dieses scheinbar unbedeutende Detail achten, aber ich bin neugierig, wie sich die SO-Community über eine Option gegenüber der anderen fühlt. Wenn Sie eine Meinung haben, geben Sie dies an und begründen Sie dies. Ich bin mir ziemlich sicher, dass Vim eine Einstellung darin begraben hat, um mir hier zu helfen, damit ich das Beste aus beiden Welten haben kann.

Meine Stimme besteht darin, Absätze einfach zu tippen, bis meine Augen bluten und die Umrisse so erscheinen lassen, wie ich will, weil ich dadurch den Text nicht mehr mit jeder Bearbeitung in der Mitte des Textes formatieren muss.

Answer 1

Abstimmung für feste Breite readme

ich zur gleichen Zeit in einer Reihe von verschiedenen Umgebungen arbeiten (mit großem Bildschirm Monitor mit Textmate, 13" Laptop mit Eclipse, die Commandline überall) kümmern. I Verwenden Sie auch verschiedene Popin-Geräte.Mac Mäuse haben das SideScroll eingebaut. Die meisten anderen Mäuse nicht.So die Mittel zum Sidescroll eine Linie möglicherweise nicht existieren.

Ich bin gekommen, um eine strengere Zeilenlänge zu bevorzugen. READMEs usw. Ich denke, dass eine Zeilenlänge von mehr als 100 Zeichen meine Fähigkeit, etwas zu lesen, absolut zerstören würde, besonders wenn ich nicht die Mittel habe, es zu verwalten Sie können nicht sicher sein, was Ihr Leser verwenden wird, ist es wahrscheinlich am besten, mit kürzeren, leichter zu lesenden Zeilenlängen zu gehen.

Answer 2

Schreiben Sie es ohne sich Gedanken über die Formatierung zu machen, formatieren Sie es dann. Wenn Sie formatieren, wird es wahrscheinlich mehr gestelzten Text erzeugen, da Sie Ihren eigenen Gedankengang unterbrechen - aber die Formatierung macht Ihren Benutzern keinen schlechten Dienst.

Vergessen Sie nicht, dass die README der erste Eindruck sein kann, den der Benutzer von Ihrer Software erhält - und Sie wissen, was sie über den ersten Eindruck sagen. Ich werde sehr frustriert von READMEs, die wirklich schlecht angezeigt werden, oder mich zum Scrollen bringen.

Insbesondere wenn Sie Dokumentation für ein Windows-basiertes Projekt schreiben, versuchen Sie, die README im Editor zu öffnen - da viele Benutzer standardmäßig Textdateien öffnen.

(Es gibt dann die Frage, welche Art von Zeilenende Sie für ein Multi-Plattform-Projekt verwenden sollten - Ich habe gesehen Projekte haben README.windows und README.linux etc, das funktioniert gut, aber erfordert eine Menge Aufwand zu behalten.)

Schließlich erinnern, dass, wenn Ihr Projekt populär ist, viel mehr Zeit damit verbracht wird, das README zu lesen, als es zu schreiben. Wenn Sie nach der Formatierung 5 Minuten brauchen, um es zu formatieren, aber 500 Personen haben es gelesen, dann haben Sie effektiv weniger als eine Sekunde pro Benutzer "ausgegeben" - für einen möglicherweise erheblichen Nutzen. Zeigen Sie :)

Answer 3

Laut deinem Avatar benutzt du Vim, also schlage ich vor, dass formatoptions = + w in Vim dein Freund ist. Es verwendet "flossed text" und spart Ihnen viel Mühe, wenn es Zeit für die Neuformatierung ist. Wrapped-Zeilen werden mit einem Leerzeichen abgeschlossen. Auf diese Weise vermeiden Sie das unerwünschte Neuformatieren von Zeilen. Wenn es Zeit zum Speichern ist, geben Sie "gggqG" ein, um die gesamte Datei neu zu formatieren. Ich habe formatoptions = tcqw für viele Jahre verwendet und ich bin vollkommen zufrieden damit.

Answer 4

Mehr als 80 Zeichen und es ist eine Schlampe zu lesen, wenn Sie nur ein Terminal mit 80 Zeichen haben.

Das klingt vielleicht wie eine Nachricht aus der Vergangenheit, aber wann brauchen Sie wirklich müssen in der Lage, die Dokumente zu lesen?Wenn alles durcheinander ist und Sie Ihr Windows-System nicht zum Laufen bringen können.

Kicken Sie keine Leute, wenn sie unten sind, verwenden Sie 80 Zeichen als harte Grenze.

Es ist kein breiterGrenzwert erforderlich. Es ist einfacher, Spalten zu lesen, die nicht zu weit sind. Es gibt einen Grund, warum Zeitungen keine Zeilen schreiben, die die ganze Zeitung umfassen (das wäre nicht lesbar). Die Alternative wäre dann, dem Benutzer-Viewer zu vertrauen, dass er sie automatisch umschließt. In der Praxis habe ich festgestellt, dass es ein Schmerz ist, in Linux (mehr, weniger, schwieriger zu grep, Emacs, vim) und in Windows-Notizblock (ich muss durch Menüs gehen, um Auto-Wrap zum Beispiel zu aktivieren).

Aus diesen Gründen sage ich bitte 80 Zeichen oder weniger.

Answer 5

Stellen Sie eine Nur-Text-Readme zur Verfügung, die leicht auf jeder Art von PC-Konfigurationen gelesen werden kann und für die Sie sich alle möglichen Schwierigkeiten beim Öffnen und Lesen vorstellen können. Aber auch eine schön formatierte PDF Version für Benutzer, die tatsächlich etwas lesen möchten.