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
So könnte die Python-Dokumentation aussehen
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.
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.
-
- User
- Beiträge: 1790
- Registriert: Donnerstag 28. Oktober 2004, 16:33
- Wohnort: Graz, Steiermark - Österreich
- Kontaktdaten:
Hast du da einen Screenshot dazu? Hier passt das nämlich.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.
Welche Klammern?- 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.
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.- 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.
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.- 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.
TUFKAB – the user formerly known as blackbird
-
- Python-Forum Veteran
- Beiträge: 16025
- Registriert: Freitag 20. Juni 2003, 16:30
- Kontaktdaten:
Ich benutze im GMI immer die Type-ahead-Suche oder setze mir gleich ein Bookmark mit Formattern (%s) im Browser, das funktioniert sehr gut.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.
My god, it's full of CARs! | Leonidasvoice vs (former) Modvoice
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:
Und danke da ihr das anpackt.
pythonist
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
Und danke da ihr das anpackt.
pythonist
- 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
bsp:
http://docs.python.org/dev/search.html? ... a=whatsnew
Bei mir klappt dein Link.jens hat geschrieben:Ist es normal das die Suche noch (?) nicht geht?
bsp:
http://docs.python.org/dev/search.html? ... a=whatsnew
Die Suchergebnisse kommen aber erst nach, da IIRC, die Suche in Javascript geschrieben ist.