JavaDoc SEO-freundlich gestalten

[inflamer]

Hallo zusammen,

ich bastle an einer Open Source-Bibliothek, welche am Ende nach allen gängigen Regeln gestaltet sein soll, wozu natürlich auch ein ausführliches JavaDoc gehört.

Dieses JavaDoc würde ich gerne zusätzlich als ein Set von Landing Pages auf meiner Webseite verwenden, um so die Bibliothek zu bewerben. Für diesen Zweck sollten einzelne HTML-Seiten möglichst SEO-optimiert sein.

Habt ihr hierfür irgendwelche Tipps?

Im Moment teste ich mit dem Standard-JavaDoc, für welches die ganzen /** ... */-"Dinger" im Code eben auch geschrieben sind. Ich schätze daher, dass die letztendliche Lösung am besten wohl nicht all zu weit vom Standard-JavaDoc entfernt sein sollte...

Als Zusatzinfo zu meinem Kenntnisstand: Ich bin in dem Thema gerade so weit drin, dass bei aktiviertem "lint" meine JavaDoc-Kommentare keine Fehler oder Warnungen generieren.

Danke!

 

[Robert Zenz]

Dieses JavaDoc würde ich gerne zusätzlich als ein Set von Landing Pages auf meiner Webseite verwenden, um so die Bibliothek zu bewerben. Für diesen Zweck sollten einzelne HTML-Seiten möglichst SEO-optimiert sein.

Ja Nein, aber eher nicht? Ich bin mir nicht ganz sicher was genau du vorhast.

Javadoc ist sehr schlecht geeignet um einen Ersteindruck einer Bibliothek oder eines Programms zu vermitteln da es auf den Klassen und nicht auf den Anwendungsfaellen aufbaut. Du kannst dann natuerlich den Mockito-Weg gehen und alles in die Javadoc reinbauen, inklusive Bildern, dann ist die Klassendokumentation selbst aber nahezu unbrauchbar. In so ziemlich allen Faellen duerften mehrere Klassen interagieren, und wo man diesen Fall dann dokumentiert ist fragwuerdig.

Du koenntest eine Paket-Dokumentation mit Javadoc machen und dann dort alles beschreiben. Da man in Javadoc auch HTML nach belieben(?) verwenden kann, geht das alles recht gut. Die Paket-Dokumentation hat eben den Vorteil dass es mehrere Klassen buendelt, aber auch hier gibt es dann wieder Probleme damit Dinge zu beschreiben die mehrere Pakete umfassen und in einer IDE ist eine Paket-Dokumentation etwas schlechter zu finden als die auf den Klassen.

In erster Linie wird ein neuer Benutzer immer Dokumentation zu Anwendungsfaellen brauchen und nicht zu einzelnen Klassen. Solche Dokumentation ist eigentlich immer "extra".

 

[inflamer]

Hallo und danke für deine Antwort!

Ich bin mir nicht ganz sicher was genau du vorhast.

Vielleicht habe ich meine Frage etwas ungenau formuliert. Die HTML-Seiten, aus denen das JavaDoc besteht, sollen, knapp formuliert, so gestaltet sein, dass Google sie als "hochwertig" einstuft und bei entsprechenden Suchbegriffen die Seiten möglichst weit oben präsentiert. Dazu ist es gemeinhin sinnvoll, dass die HTML-Seiten sowohl Inhaltlich als auch von der HTML-Struktur her möglichst Google-freundlich gestaltet sind.

Darauf zielte meine Frage ab. Ich dachte z.B. an sowas wie DocLets, die auf suchmaschinenoptimierte HTMLs erzeugen oder sowas. Im Moment, wie ich oben schon erwähnte, generiere ich ziemlich standardisierte Seiten wie diese hier: https://docs.oracle.com/javase/8/docs/api/java/lang/String.html

(Was die von dir erwähnten Anwendungsfälle angeht, gebe ich dir recht, und ich habe im Zuge des Schreibens der JavaDocs auch schnell gemerkt, dass eine Anleitung mit Beispielen eigentlich Pflicht ist. Darum enthalten die paar Hauptklassen auch Code-Beispiele oben in der Klassenbeschreibung. Welches die Hauptklassen sind, findet der Anwender auch schnell heraus angesichts der überschaubaren Gesamtmenge an Klassen und der überlegten Namensgebung...)

 

[inflamer]

Zu spät für ein Edit:
"die suchmaschinenoptimierte HTMLs erzeugen" (ohne "auf")

 

[httpdigest]

Hast du dich denn selbst schon mit dem Thema SEO beschäftigt und Research betrieben, basierend auf der Vielzahl an öffentlich zugänglichen Informationen, z.B. von Google selbst?
Ich würde erstmal folgende Seiten und verlinkte Unterseiten durcharbeiten: https://developers.google.com/search/docs/fundamentals/seo-starter-guide

Auch sind die "Web Vitals" wichtig: https://web.dev/articles/vitals
für Dinge wie "Layout Shifts", aber auch generell die Responsiveness der Seite.

 

[Robert Zenz]

Vielleicht habe ich meine Frage etwas ungenau formuliert. Die HTML-Seiten, aus denen das JavaDoc besteht, sollen, knapp formuliert, so gestaltet sein, dass Google sie als "hochwertig" einstuft und bei entsprechenden Suchbegriffen die Seiten möglichst weit oben präsentiert. Dazu ist es gemeinhin sinnvoll, dass die HTML-Seiten sowohl Inhaltlich als auch von der HTML-Struktur her möglichst Google-freundlich gestaltet sind.

Javadoc selbst unterstuetzt nur einen verkleinerten Satz an HTML Elementen, aber das wuerde ich natuerlich nicht hindern einen eigenen Javadoc-Prozessor zu schreiben welcher die Struktur "aufarbeitet" und alles in eine enstprechende Vorlage einbettet. Die billigste Variante welche mir einfaellt waere das Javadoc "normal" schreiben zu lassen in HTML Dateien und dann mit Pandoc diese so umzubauen dass sie deinen Vorstellungen entsprechen. Ansonsten kannst du dir ein eigenes Doclet schreiben welches dann das Javadoc direkt aus dem Quellcode praesentiert bekommt und dann dieses entsprechend aufarbeiten.

 

[Manul]

Darauf zielte meine Frage ab. Ich dachte z.B. an sowas wie DocLets, die auf suchmaschinenoptimierte HTMLs erzeugen oder sowas. Im Moment, wie ich oben schon erwähnte, generiere ich ziemlich standardisierte Seiten wie diese hier: https://docs.oracle.com/javase/8/docs/api/java/lang/String.html

Welche "trotz" Standardisierung und Nicht-SEO-Optimierung so ziemlich das oberste Suchergebnis ist, wenn man "java string" bei Google eingibt ...

 

[KonradN]

Entschuldige, wenn ich da jetzt gerade etwas hinterfrage:

SEO Optimierung und JavaDoc passen da gerade nicht wirklich zusammen. In JavaDoc geht es ja in erster Linie um die Beschreibung der Klassen Deiner Open Source Bibliothek. Und die sollten vom Namen her doch schon relativ eindeutig sein. Es mag evtl. paar Klassennamen geben, die in vielen Bibliotheken vorkommen (StringUtils oder so), aber jemand der in Google sucht, der wird doch vermutlich den Namen der Library zusammen mit dem Klassennamen angeben. Und damit wird doch vermutlich Deine Seite mit einer der Top Treffer sein, denn diese Kombination wird es nicht viel geben. Evtl. paar SO Threads aber sonst?

Daher ist die Frage, in wie weite eine Optimierung überhaupt notwendig ist. Ich sehe es hier ähnlich wie bei Optimierungen in der Entwicklung: Erst einmal schauen, ob dies überhaupt notwendig ist. Oder hast Du bereits festgestellt, dass dies dringend notwendig ist und ich habe das schlicht überlesen (dann täte es mir leid).

Anders wäre es, wenn es darum geht, deine Library zu finden. Aber das sollte dann eine Webseite sein von Deiner Library und nicht die API Dokumentation per JavaDoc. (siehe dazu auch #2 von @Robert Zenz).

 

[DasFrageezeichen]

Vielleicht hier im Kontext der Frage/Thema auch mal einen Blick wert:

Free Java Doc hosting for open source projects - javadoc.io

www.javadoc.io

ich persönlich würde nicht versuchen wollen, einen eigenen Parser schreiben zu wollen.

 

[inflamer]

Vielen Dank für eure Antworten!

Hast du dich denn selbst schon mit dem Thema SEO beschäftigt [...]

Mit SEO kenne ich mich ziemich aus, z.B. kommt meine Website bei dem Google-Testtool https://pagespeed.web.dev/?hl=de bei allen 4 Indikatoren auf 100%.

Das erwähne ich an dieser Stelle nur, weil dasselbe Tool für die von mir bereits als Beispiel genannte String-Javadoc-Seite ( https://docs.oracle.com/javase/8/docs/api/java/lang/String.html ) recht viele Mängel meldet. Die Seite ist mit dem Standard-Javadoc-Tool erstellt. Darum meine Frage nach einem Doclet, welches eben auf SEO einen Schwerpunkt hat.

@Robert Zenz, DasFrageezeichen
So ein Doclet selbst zu schreiben wäre wohl eine Lebensaufgabe. Pandoc konvertiert, wenn ich das richtig sehe, nur zwischen Formaten hin und her(?)

@KonradN. Kein Problem, dass du hinterfragst! Im Grunde eignet sich alles an HTML-Dokumenten, was einen ausreichenden Textanteil hat, als Landing Page und damit für SEO-Optimierung. Optimierbedürftig sind die mit Standard-Javadoc erzeugten HTML-Seiten allemal (siehe oben). Potenzielle Sucher, so jedenfalls meine Rechnung, würden halt nach Begriffen wie "qr code to eps java" suchen, wenn sie nach einer Java Library suchen, welche QR Codes nach EPS exportiert. Und da diese Begriffe mit einer ausreichenden Häufigkeit in der betr. Klassenbeschreibung vorkommen, eignen sich JavaDocs zumindest meiner Einschätzung nach hervorragend als "Landing Page". Vor allem wenn man sie zusätzlich für Google optimieren könnte...

@Manul.

"Welche "trotz" Standardisierung und Nicht-SEO-Optimierung so ziemlich das oberste Suchergebnis ist, wenn man "java string" bei Google eingibt ..."

Für's Ranking bei Google spielt eben auch die Anzahl von Links eine Rolle, die auf eine URL zeigen. Und davon gibt es im Falle der Oracle-String-Seite quasi undendlich viele. Jedes ins Netz gestellte noch so kleine Javadoc enthält garantiert gleich zig Links zur besagten URL.

Aber ok, anscheinend gibt's so ein Doclet nicht, damit wäre meine Frage beantwortet. Danke nochmal!

 

[KonradN]

Potenzielle Sucher, so jedenfalls meine Rechnung, würden halt nach Begriffen wie "qr code to eps java" suchen, wenn sie nach einer Java Library suchen, welche QR Codes nach EPS exportiert.

Aber bei so einer Suche will ich doch keine API Regerenz! Die API Referenz ist doch nur dann interessant, wenn ich Fragen zu der API habe.

Und da ist immer die Frage; Ist Google dann das Tool der Wahl?
Ich habe einige JavaDoc Local auf dem Rechner - da suche ich in der JavaDoc selbst.
Oder bindet die iDE JavaDoc automatisch ein (über Maven Repository)?

Das ist mein Punkt. Du willst mir also nicht bei der genannten Suche irgend eine Klasse geben von Dir.

Und wenn ich nach InflamerLib SuperDupperClass suche, dann sind die generierten JsvaDoc Seiten ok, denn andere Webseiten werden dazu nicht viel schreiben oder sie haben dann einen Link zu der Klassen API …

Aber das ist nur meine Sicht und ich stehe nicht für alle Entwickler oder so, Aber evtl. willst du drüber nachdenken, ob du derzeit nicht ggf. „Zeit verschwendest“.

 

[inflamer]

Die API, auf der man landet, wäre halt nur eine "Landing Page" mittels der man im nächsten Schritt (z.B. über einen gut sichtbar platzierten Link) auf die Main-Seite gelangt, mit vollständiger Beschreibung dessen, wass die Lib so alles kann, Download usw.

JavaDoc, welches viel Mühe zu schreiben war und ohnehin fertig ist, bietet (in meinem Fall) halt direkt mal 2 Dutzend zusätzliche Chancen gefunden zu werden. Haben oder nicht haben.

 

[Robert Zenz]

Pandoc konvertiert, wenn ich das richtig sehe, nur zwischen Formaten hin und her(?)

Du kannst natuerlich HTML zu HTML konvertieren und dabei Filter anwenden welche die Sache umbauen.

 

[mrBrown]

Mit SEO kenne ich mich ziemich aus, z.B. kommt meine Website bei dem Google-Testtool https://pagespeed.web.dev/?hl=de bei allen 4 Indikatoren auf 100%.

Das erwähne ich an dieser Stelle nur, weil dasselbe Tool für die von mir bereits als Beispiel genannte String-Javadoc-Seite ( https://docs.oracle.com/javase/8/docs/api/java/lang/String.html ) recht viele Mängel meldet. Die Seite ist mit dem Standard-Javadoc-Tool erstellt. Darum meine Frage nach einem Doclet, welches eben auf SEO einen Schwerpunkt hat.

Hast du das denn mal über dein eigenes Javadoc laufen lassen? Dein Beispiel ist immerhin 10 Jahre alt und dazu noch von Oracle gehostet, mit entsprechendem Javascript für z.B. Cookies und Tracking und schlecht konfiguriertem Webserver, das zieht Performance runter.

Standard-Javadoc + vernünftiger Webserver dürfte schon nah an 100% sein.

 

[inflamer]

Du hast absolut recht! Die neuen Docs "bringen's" tatsächlich.

Wald vor lauter Bäumen und so... 😯😊

"Leistung" und "SEO" werden auf Anhieb mit 100 bewertet. "Barrierefreiheit" und "Best Practices" haben 97 respektive 96, wobei beides durch eine einfache Manipulation an der CSS-Datei leicht auf ebenfalls 100 zu bringen sein dürfte. (Unter anderem besteht ein mangelnder Kontrast bei der Farbe der Textlinks - man konnte es bei dem blassen Hellblau ja schon ahnen, na ja...)

Ich wäre nie drauf gekommen, dass sie sich die Mühe gemacht haben, den HTML-Code zu optimieren, zumal optisch zwischen den 10 Jahre alten Docs und den aktuellen kein Unterschied feststellbar zu sein scheint.

Vielen Dank! Damit ist ein größeres Problem gelöst, ich war schon ein bisschen ratlos.