Wie baut man ein System a la MSDN auf?
Hallo,
was ich mich im Moment frage - in der MSDN gibt's ja eine sehr umfangreiche Referenz zu den .NET-Klassen ... wie baut Microsoft das auf?
Sie werden es kaum per Hand schreiben, sondern wohl so etwas wie die XML-Kommentare nutzen, um sich das zu erzeugen - ABER: Es wird zusätzlich nach Versionen unterschieden, nach Sprachen, ...
Wie macht man so etwas?
Angenommen, man möchte für seine eigenen Produkt ein entsprechendes Portal bereitstellen, wie würde man an so etwas herangehen, wenn man zunächst mal nur den XML-Output des C#-Compilers hat?
Viele Grüße,
Golo
Wissensvermittler und Technologieberater
für .NET, Codequalität und agile Methoden
hallo Golo,
wenn es auf den Code-Kommentaren basieren soll, dann soviele Informationen wie möglich in die Code-Kommentare einbetten und mittels XSLT die Darstellung in die gewünschte Form bringen. Das wäre mein Vorschlag.
-yellow
Selbst ein Weg von tausend Meilen beginnt mit einem Schritt (chinesisches Sprichwort).
Mein Blog: Yellow's Blog auf sqlgut.de
Hallo Golo,
Es wird zusätzlich nach Versionen unterschieden, nach Sprachen, ...
nach Versionen wird vermutlich mit #if/#ifdef im Code unterschieden.
Und was meinst du mit Sprachen? Programmiersprachen oder natürliche Sprachen?
Wobei ich so oder so nicht denke, dass Microsoft die XML-Kommentare direkt in den Code schreibt. Das sind ja manchmal so lange Dinger, da sieht man ja vor Kommentaren den Code kaum. Außerdem wird die Dokuvermutlich nicht von den Entwicklern erstellt, sondern von extra Autoren. Ich gehe davon aus, das Microsoft ein eigenes interes Verwaltungssystem dafür haben, dass auch die Übersetzungen in andere Programmier und natürliche Sprachen unterstützt.
herbivore
Kennst Du eine Software, die ein Basissystem a la MSDN bereitstellt, in dem man so etwas pflegen könnte? Quasi die MSDN + Verwaltungsoberfläche, aber ohne Inhalte?
Mit Sprachen meinte ich natürliche Sprachen.
Wissensvermittler und Technologieberater
für .NET, Codequalität und agile Methoden
Hallo Golo,
nein, wenn ich mit meiner Vermutung recht habe, ist das ein internes System von Microsoft. Und sowas von anderen Anbietern kenne ich nicht, wobei ich auch noch nie wirklich nach sowas gesucht habe.
Man kommt ja auch schon mit XML-Kommentaren im Code und NDoc oder Sandcastle relativ weit.
herbivore
Es ist doch eigentlich ein Content-Management-System. Bloß halt mit XML statt HTML Output.
Ansonsten werden doch nur Artikel zu bestimmten Themen zugeordnet und miteinander verlinkt.
Als Basis dafür müßte man die XML-Kommentare aus dem Code nehmen, und diese dann weiter-bearbeiten und/oder übersetzen können.
Interessant wäre dann allerdings, wie man es schafft, die Doku auf den neuesten Stand zu bringen, nachdem eine neue Version released wurde. (Ohne wieder von vorne anzufangen, meine ich).
Weeks of programming can save you hours of planning
Exakt 😉.
Wissensvermittler und Technologieberater
für .NET, Codequalität und agile Methoden
Genau. Da hilft wohl nur selbst programmieren...
Wäre aber ne feine Sache, mir reichen die popeligen XML-Kommentare auch nicht so richtig...
Weeks of programming can save you hours of planning
hallo,
wie herbivore oben schon erwähnt hat, wird Microsoft sicher Mitarbeiter nur für die Dokumentation, sprich' das Füllen der MSDN Seiten einsetzen. Und das ist ein wichtiger Punkt den man nicht ausser acht lassen sollte. Soll die Dokumentation direkt vom Entwickler geschrieben werden und mehr nicht, oder soll der Inhalt von Redakteuren, Autoren oder wie auch immer aufgearbeitet und bereitgestellt werden. Diese Entscheidung sollte m. E. vor dem Suchen bzw. selber programmieren getroffen werden.
-yellow
Selbst ein Weg von tausend Meilen beginnt mit einem Schritt (chinesisches Sprichwort).
Mein Blog: Yellow's Blog auf sqlgut.de
Ist doch ganz klar. Ich stell mir eine ganze Galeere voller Dokumentatoren und Praktikanten ein, die übernehmen das für mich... Keine Ahnung wie das bei euch so aussieht.
Weeks of programming can save you hours of planning
Also zumindest in meinem Fall wird's nicht auf Redakteure hinauslaufen, sondern es wird bei den Entwicklern bleiben ... mangels Ressourcen.
Wissensvermittler und Technologieberater
für .NET, Codequalität und agile Methoden
Hallo Golo,
es gibt diverse Software, mit denen sich ein Helpsystem aufbauen läßt, a la msdn.
durcforste mal dieses Wiki
http://www.mshelpwiki.com/wiki/tiki-index.php?page=MSHelpWiki
Hmmm ... was mir ganz nützlich erschien, ist der CHM-Merger ... so in der Theorie zumindest.
In der Praxis funktioniert das Ding nämlich eher weniger 😦
Frage wäre nun, gibt's so was auch für Sandcastle-erzeugte Webseiten?
Wissensvermittler und Technologieberater
für .NET, Codequalität und agile Methoden
Hi Golo,
ich habe mal vor einiger Zeit an einem kurzen Vortrag/Präsentation von http://www.datadax.de/ teilgenommen.
Die Software wäre wohl evtl was für dich.
Da geht es auch darum Dokus, Manuals, etc aus Code Internen Kommentaren zu generieren.
Leider scheiterte es damals aus finanziellen Gründen an einer Zusammenarbeit.
Aber ich war sehr angetan von der Software.
Die haben uns auch eine kostenlose Testversion angeboten, von daher könntest einfach mal Kontakt mit denen aufnehmen.
Gruß,
Tom
Original von Golo
Hmmm ... was mir ganz nützlich erschien, ist der CHM-Merger ... so in der Theorie zumindest.In der Praxis funktioniert das Ding nämlich eher weniger 😦
Frage wäre nun, gibt's so was auch für Sandcastle-erzeugte Webseiten?
So, nachdem ich nun mal einen Blick auf die Struktur von der von Sandcastle erzeugten Webseite geworfen habe, ist mir klar geworden, dass das total easy ist ... hier also die Lösung, falls es noch jemand braucht:
Die Datei WebTOC.xml enthält den anzuzeigen Baum als XML-Baum, diesen einfach ergänzen, und das war's ... um zwei Seiten zu mergen, muss man halt den einen Baum in den anderen einhängen, und gut ist 🙂
Was mir jetzt noch fehlt, ist eine Idee, wie man das mit verschiedenen Versionen machen kann, aber ich denke, auch dazu fällt mir noch was ein ... zur Not geht's auch mit einzelnen Knoten für jede Version ...
Wissensvermittler und Technologieberater
für .NET, Codequalität und agile Methoden
Wenn ich es richtig verstehe, bräuchtest du ein Tool, daß eine solche WebTOC.xml Datei erstellt und es dir erlaubt, beliebige (HTML?)-Dateien mit einem Eintrag zu verknüpfen. So kannst du für jede Sprach- u.a. Versionen eigenen Content zur Verfügung stellen oder den automatisch von SandCastle etc. generierten Content zu verwenden.
Weeks of programming can save you hours of planning
Das stimmt. Wobei ich mir so ein Ding wohl selbst schreiben werde, denn außer ein bisschen Knotengewurschtel in der XML-Datei ist das ja nix groß ... es sei denn, Du kennst was entsprechendes 😉?
Wissensvermittler und Technologieberater
für .NET, Codequalität und agile Methoden
Nö, wenn dann würde ich sowas selbst programmieren. Aber im Moment bin ich mit was anderem beschäftigt... Klar macht das Mühe, aber der Vorteil einer richtigen Anwendung wäre, daß man immer alle Versionen in einer Datenbank (oder woanders) hat und die einzelnen Textbausteine sehr komfortabel ändern oder ersetzen kann. Ein CMS eben im weitesten Sinne...
Weeks of programming can save you hours of planning
Ich habe gerade eine Ausgabe der dotnetpro vor mir liegen die einen Artikel zum Thema Softwaredokumentation enthält. In diesem Artikel werden zwei Formate für das "Single-Source-Publishing" genannt: DITA und DocBook. Vielleicht hilft dir das weiter.