So könnte die Python-Dokumentation aussehen

Stellt hier eure Projekte vor.
Internetseiten, Skripte, und alles andere bzgl. Python.
mitsuhiko
User
Beiträge: 1790
Registriert: Donnerstag 28. Oktober 2004, 16:33
Wohnort: Graz, Steiermark - Österreich
Kontaktdaten:

Jetzt gibts auch die "interaktive" Version zum Testen: http://pydoc.gbrandl.de:3000/

Kurzzusammenfassung: rät URLs (ähnlich wie bei php.net), hat Kommentare, man kann mal testweise die Sidebar nach rechts bugsieren, Feeds, Antispam und ein Adminpanel unter http://pydoc.gbrandl.de:3000/admin/

Zugangsdaten sind testuser:password

Viel Spaß beim Testen :-)
TUFKAB – the user formerly known as blackbird
apollo13
User
Beiträge: 827
Registriert: Samstag 5. Februar 2005, 17:53

Willst du mal nen Anker setzen, dass unter "Moderate Comments -> View" gleich hinuter zu dem/den Comments gesprungen wird?
Y0Gi
User
Beiträge: 1454
Registriert: Freitag 22. September 2006, 23:05
Wohnort: ja

Insgesamt: Gute Arbeit! Etwas gewöhnungsbedürftig, aber das ist bei Änderungen ja nunmal oft so.

Ein paar Dinge, die mir so auffallen:

- Die Beschreibungen zu den Hauptlinks der Startseite überschneiden sich an einigen Stellen mit dem Titel darüber, was es schlechter lesbar macht. Da könnte ein leicht größerer Abstand einiges bewirken.

- Auch wenn es nett einheitlich aussieht: Die Klammern sind überflüssig und der Verzicht auf diese trägt ebenfalls zu besserer Lesbarkeit bei. Eine Option wäre zur Not, die Klammern per CSS mit :before und :after hinzuzufügen, damit man sie zumindest für sich selbst deaktivieren kann.

- Ich persönlich benutze den "Global Module Index" *sehr* viel. Der ist mir fast ein bisschen zu weit unten, auch wenn ich mit einem schlanken Browserfenster noch nicht scrollen muss. Fraglich, wie weit die (durchaus sinnvolle) Gruppierung so ideal ist, aber sowas wie "Macintosh Library Modules" und "Distributing/Documenting Python Modules" ist IMHO etwas, das man sicherlich weitaus seltener liest als den GMI - und deswegen ist hier die Reihenfolge für mich sehr suboptimal. Zum Vergleich: Ich benutze sehr viel die .chm-Doku (auch unter Linux; Index und Suchfunktion sind doch irgendwie praktischer als über einen Webbrowser) und dort (wie auch im Web) kommt der GMI an sehr früher Stelle - zu Recht. Bitte das nochmal überdenken.

- Warum müssen die Feeds unbedingt RSS sein? ATOM 1.0 ist der (einzige?) abgesegnete, saubere Standard und jeder halbwegs brauchbare Client kann es ebenso lesen. RSS ist nur ein inkompatibler Formatdschungel mit zahlreichen Problemen, die ATOM löst. Die gängigen ATOM vs. RSS-Vergleiche sollten bekannt oder ansonsten leicht auffindbar sein.
mitsuhiko
User
Beiträge: 1790
Registriert: Donnerstag 28. Oktober 2004, 16:33
Wohnort: Graz, Steiermark - Österreich
Kontaktdaten:

Y0Gi hat geschrieben: - Die Beschreibungen zu den Hauptlinks der Startseite überschneiden sich an einigen Stellen mit dem Titel darüber, was es schlechter lesbar macht. Da könnte ein leicht größerer Abstand einiges bewirken.
Hast du da einen Screenshot dazu? Hier passt das nämlich.
- Auch wenn es nett einheitlich aussieht: Die Klammern sind überflüssig und der Verzicht auf diese trägt ebenfalls zu besserer Lesbarkeit bei. Eine Option wäre zur Not, die Klammern per CSS mit :before und :after hinzuzufügen, damit man sie zumindest für sich selbst deaktivieren kann.
Welche Klammern?
- Ich persönlich benutze den "Global Module Index" *sehr* viel. Der ist mir fast ein bisschen zu weit unten, auch wenn ich mit einem schlanken Browserfenster noch nicht scrollen muss. Fraglich, wie weit die (durchaus sinnvolle) Gruppierung so ideal ist, aber sowas wie "Macintosh Library Modules" und "Distributing/Documenting Python Modules" ist IMHO etwas, das man sicherlich weitaus seltener liest als den GMI - und deswegen ist hier die Reihenfolge für mich sehr suboptimal. Zum Vergleich: Ich benutze sehr viel die .chm-Doku (auch unter Linux; Index und Suchfunktion sind doch irgendwie praktischer als über einen Webbrowser) und dort (wie auch im Web) kommt der GMI an sehr früher Stelle - zu Recht. Bitte das nochmal überdenken.
GMI kann man sicher raufbewegen, ist aber zusätzlich auch in der Topbar oben rechts. CHM müssen wir uns auch noch was einfallen lassen.
- Warum müssen die Feeds unbedingt RSS sein? ATOM 1.0 ist der (einzige?) abgesegnete, saubere Standard und jeder halbwegs brauchbare Client kann es ebenso lesen. RSS ist nur ein inkompatibler Formatdschungel mit zahlreichen Problemen, die ATOM löst. Die gängigen ATOM vs. RSS-Vergleiche sollten bekannt oder ansonsten leicht auffindbar sein.
Das ist ganz einfach. RSS ist schnell implementiert, wird von jedem Client unterstützt, funktioniert auch ohne DTD oder xmlns. Ich sehe ein, dass RSS ein scheiß Format ist, aber für so einfach Feeds ist es ideal.
TUFKAB – the user formerly known as blackbird
Y0Gi
User
Beiträge: 1454
Registriert: Freitag 22. September 2006, 23:05
Wohnort: ja

Guckst du:

Bild
Leonidas
Python-Forum Veteran
Beiträge: 16025
Registriert: Freitag 20. Juni 2003, 16:30
Kontaktdaten:

Y0Gi hat geschrieben:Fraglich, wie weit die (durchaus sinnvolle) Gruppierung so ideal ist, aber sowas wie "Macintosh Library Modules" und "Distributing/Documenting Python Modules" ist IMHO etwas, das man sicherlich weitaus seltener liest als den GMI - und deswegen ist hier die Reihenfolge für mich sehr suboptimal.
Ich benutze im GMI immer die Type-ahead-Suche oder setze mir gleich ein Bookmark mit Formattern (%s) im Browser, das funktioniert sehr gut.
My god, it's full of CARs! | Leonidasvoice vs (former) Modvoice
pythonist
User
Beiträge: 40
Registriert: Sonntag 14. Mai 2006, 17:28

Also erst mal ich finds genial das sich das was tut, weil die aktuelle Dokumentation ist alles Andere als zeitgemäß.

Ich find aber die Alte auch leichter zu lesen, wobei man das sicher durch anpassen der Farben Schriften änder kann.

Wichtig für ne neue Doku find ich:
  • Gute Kommentarfunktion weil man so relativ schnell vile Code-Beispiele bekommt
    Möglichkeit der Übersetzung in ander Sprachen damit die möglichkeit besteht die Doku wenigstens Teilweiße in ander Sprachen zu übersetzen
    Vieleicht noch Quellcode-Ansicht der einzelnen Module
Ich hoffe das Feedback hilft n bisl.
Und danke da ihr das anpackt.

pythonist
Benutzeravatar
jens
Python-Forum Veteran
Beiträge: 8502
Registriert: Dienstag 10. August 2004, 09:40
Wohnort: duisburg
Kontaktdaten:

pythonist hat geschrieben:
  • Vieleicht noch Quellcode-Ansicht der einzelnen Module
Das würde ich allerdings auch super finden!

GitHub | Open HUB | Xing | Linked in
Bitcoins to: 1JEgSQepxGjdprNedC9tXQWLpS424AL8cd
Benutzeravatar
Quash
User
Beiträge: 9
Registriert: Donnerstag 5. Juli 2007, 01:53

Sehr gut, gefällt mir!
Benutzeravatar
jens
Python-Forum Veteran
Beiträge: 8502
Registriert: Dienstag 10. August 2004, 09:40
Wohnort: duisburg
Kontaktdaten:

Ist es normal das die Suche noch (?) nicht geht?

bsp:
http://docs.python.org/dev/search.html? ... a=whatsnew

GitHub | Open HUB | Xing | Linked in
Bitcoins to: 1JEgSQepxGjdprNedC9tXQWLpS424AL8cd
rafael
User
Beiträge: 189
Registriert: Mittwoch 26. Juli 2006, 16:13

jens hat geschrieben:Ist es normal das die Suche noch (?) nicht geht?

bsp:
http://docs.python.org/dev/search.html? ... a=whatsnew
Bei mir klappt dein Link.
Die Suchergebnisse kommen aber erst nach, da IIRC, die Suche in Javascript geschrieben ist.
Benutzeravatar
jens
Python-Forum Veteran
Beiträge: 8502
Registriert: Dienstag 10. August 2004, 09:40
Wohnort: duisburg
Kontaktdaten:

Ah, jo... NoScript ;)

IMHO gehört da ein <noscript>Please enable Javascript</noscript> o.ä. hin ;)

GitHub | Open HUB | Xing | Linked in
Bitcoins to: 1JEgSQepxGjdprNedC9tXQWLpS424AL8cd
Antworten