Hallo,
ich frage mich schon seit längerem, ob die Dokumentation (sowohl User- als auch Devdocs) noch weiter ausgebaut wird? Denn selbst in der User-Dokumentation ist nur der Standardfall beschrieben. Weicht das aktuelle Problem etwas davon ab, dann findet man schon nichts mehr in der Dokumentation darüber. Das finde ich sehr schade.
In den devdocs ist es noch schlimmer. Gerade das Thema Attribute kommt dort viel zu kurz. Das wird mit einer Code Zeile abgehakt. Und die phpdoc Code Kommentare sind anscheinend auch nur da, dass es sie gibt. Da findet man nichts darüber, wofür die Parameter sind und absolut keine Beschreibung darüber, was die Methode macht.
Das hatte mir beispielsweise beim letzten Mal acht Stunden Zeit gekostet, herauszufinden wie man die Produkteigenschaften mitsamt Freitextfelder im Produkt Listing lädt. Man findet in den Devdocs auch nichts darüber, was SearchBundle macht. Es steht zwar dort, dass es Bundles gibt und dass es das SearchBundle gibt, aber nicht wofür es gut ist usw.
MFG
derwunner
Die Dokumentation wird stetig erweitert - sei es um neue Artikel, oder um Aktualisierungen/Ergänzungen bestehender Artikel. Für die normale User-Doku kannst Du uns gerne im jeweiligen Artikel Wiki-Vorschläge zukommen lassen. Bei der dev-doku hast du sogar die Möglichkeit, aktiv über github mitzuarbeiten:
GitHub - shopware/devdocs: Shopware 5 Developers Website
Hi,
das SearchBundle ist ja beispielsweise hier erläutert SearchBundle
Was genau fehlt dir da an Info?
Bzgl. Benutzerdoku wäre auch ein konkretes Beispiel sinnvoll, was dir fehlt. Gerne liefern wir auch da Inhalte nach, wenn diese sinnvoll sind. Natürlich können wir in der Doku nicht jeden Fall, abweichend vom Standardweg, aufnehmen.
Wie Andre aber auch geschrieben hat, wird an jedem Tag an der Doku gearbeitet, diese erweitert, verbessert etc. - Das gilt ebenfalls für die Entwicklerdoku
Sebastian
@AndreHerking schrieb:
Die Dokumentation wird stetig erweitert - sei es um neue Artikel, oder um Aktualisierungen/Ergänzungen bestehender Artikel. Für die normale User-Doku kannst Du uns gerne im jeweiligen Artikel Wiki-Vorschläge zukommen lassen. Bei der dev-doku hast du sogar die Möglichkeit, aktiv über github mitzuarbeiten:
https://github.com/shopware/devdocs
Das ist ja alles richtig und schön. Es wäre aber denke ich sinnvoller, dass es gleich vom Autor dokumentiert wird. In der Commit Historie sieht man, dass zwar Tickets erledigt werden, beim phpdoc aber keine kurze Beschreibung der neuen Methode eingefügt wird. Gerade der Autor sollte doch darüber bescheid wissen, warum etwas wie getan wurde. Das ganze nachträglich von der Community einzupflegen, wo sich erst wieder jemand einarbeiten muss, ist denke ich nicht Sinn und Zweck der Sache. Außerdem, einen Satz zu schreiben dauert auch nicht länger, das ist vielleicht maximal eine Minute. So viel Zeit sollte jeder Entwickler, selbst bei einem engen Zeitplan, haben.
@SebastianKlöpper schrieb:
Hi,
das SearchBundle ist ja beispielsweise hier erläutert https://developers.shopware.com/developers-guide/shopware-5-search-bundle/
Was genau fehlt dir da an Info?
Um mal bei dem Beispiel SearchBundle zu bleiben: Es passiert dort viel im Hintergrund. Es gibt viele Klassen, die verschiedene Dinge tun. Es zwar gut und schön, dass es die gibt, denn das spart einem Arbeit, selbst Queries zu schreiben und eventuell Gefahr zu laufen, das ein oder andere zu vergessen, was Shopware braucht. Man muss aber wissen, dass die da sind. Vorallem wäre es schön, wenn man grob bescheid wüsste, was diese ganzen Gateways usw. machen.
@derwunner schrieb:
Außerdem, einen Satz zu schreiben dauert auch nicht länger, das ist vielleicht maximal eine Minute. So viel Zeit sollte jeder Entwickler, selbst bei einem engen Zeitplan, haben.
wenn ich das nur lese…klar eine gute Doku wäre schön, aber es ist nicht nur eine Minute. Hab doch etwas Respekt vor der Arbeit. Solche Sprüche kenne ich nur von den Leuten die keine Ahnung haben.
@NextMike schrieb:
@derwunner schrieb:
Außerdem, einen Satz zu schreiben dauert auch nicht länger, das ist vielleicht maximal eine Minute. So viel Zeit sollte jeder Entwickler, selbst bei einem engen Zeitplan, haben.
wenn ich das nur lese…klar eine gute Doku wäre schön, aber es ist nicht nur eine Minute. Hab doch etwas Respekt vor der Arbeit. Solche Sprüche kenne ich nur von den Leuten die keine Ahnung haben.
Doch, weil ich das täglich selbst so praktiziere. Reicht doch kurz und knapp, aber dann weiß jeder etwas damit anzufangen.
Das Motto „Wenn du was suchst, dann schau halt im Code nach“ wird häufig so gemacht, ist aber schlecht, weil es dem Suchenden Stunden an Zeit kostet, die Stellen zu finden, die man braucht. Meistens ist das auch nicht so einfach aufgrund großer und komplizierter Software, die zig Querverweise inne hat. Mit ein bisschen Doku wäre das eine Sache von Minuten.
Und natürlich habe ich Respekt vor dem Ganzen, auch wenn es vielleicht nicht so rüber kam. Shopware ist immer noch die beste frei verfügbare PHP Shop Lösung, die es gibt. Nur, wenn man nie die Leute auf etwas hinweist, dann wird sich auch nichts ändern. Ich wusste auch nicht, wie ich es schöner bzw. netter formulieren hätte können.
@derwunner schrieb:
Vorallem wäre es schön, wenn man grob bescheid wüsste, was diese ganzen Gateways usw. machen.
99% der Anwender / Entwickler müssen überhaupt nicht wissen, wie das search bundle funktioniert - das ist ja auch genau Sinn und Zweck dieses bundles. Du musst nur die interfaces kennen und diese sind gut dokumentiert. Die restlichen 1%, die einen Schritt weiter gehen wollen und die gateways anpassen müssen / wollen, die sollten versiert genug sein, um sich das Wissen in wenigen Minuten selber aneignen zu können. Irgendeine intern genutzte private Methode muss man nicht ausführen, da jeder Entwickler nur gegen die bekannten interfaces programmiert und die dabei zugrunde liegende Implementierung vollkommen irrelevant ist.
Viele Grüße
@derwunner schrieb:
Und natürlich habe ich Respekt vor dem Ganzen, auch wenn es vielleicht nicht so rüber kam. Shopware ist immer noch die beste frei verfügbare PHP Shop Lösung, die es gibt. Nur, wenn man nie die Leute auf etwas hinweist, dann wird sich auch nichts ändern. Ich wusste auch nicht, wie ich es schöner bzw. netter formulieren hätte können.
das sind Basics: indem Du die Arbeit nicht mit Wörtern „ist nur eine Minute“ bagatellisiert und gleichzeitig auch die guten Sachen ansprichst. Auch Shopware vorzuschreiben wie die Entwickler zu arbeiten haben finde ich nicht angebracht. Auch dass Du hier und da Zeit verlierst, ist nicht unser Problem.