Verwenden von MAML für die konzeptionelle Dokumentation der Bibliothek [geschlossen

Question

Ich arbeite an einer neuen Bibliothek und verwende XML -Kommentare für die API -Dokumentation zusammen mit Sandcastle, die wirklich gut funktioniert.

Aber ich muss zusätzliche Dokumentation schreiben, die Konzepte, allgemeine Architektur, funktionierende Demos usw., Klassendiagramme usw. abdeckt.

Ich habe 2 Optionen:

1. Verwenden Sie einen Wiki -Engine und schreiben Sie einen Dokumentationswiki -Stil.
2. Verwenden Sie MAML, was für diesen Zweck zu sein scheint.

Die Verwendung von Wiki scheint eine sichere Lösung zu sein, da es viele stabile, beliebte und kostenlose Motoren gibt, aber API und konzeptionelle Dokumentation werden nicht Hand in Hand gehen (Vernetzung, Aussehen usw.). Die Verwendung von MAML bedeutet eine Lernkurve, und ich bin mir nicht sicher, wie reif sie ist und was ihre Vor-/Nachteile sind.

Haben Sie MAML/Wiki für diesen Zweck verwendet und was waren Ihre Erkenntnisse? Was würdest du mir vorschlagen?

Answer 1

Persönlich liebe ich die Freiheit, mit einem Wiki zu arbeiten. Zu diesem Zeitpunkt haben Sie einige anständige Möglichkeiten für die Bearbeitung von MAML

• DocProject
• Sandcastle Help File Builder

Ich kann nicht viel mit DocProject sprechen (obwohl es gut aussieht). Im Moment verwende ich SHFB, um die API -Dokumentation und einige konzeptionelle Dokumente in MAML zusammenzuführen. Der Herausgeber ist anständig und reicht mehr als für meine Bedürfnisse. Ich kann einfach ein Inhaltsverzeichnis und eine Verbindung zwischen meiner API und konzeptionellen Dokumenten einrichten. Eine gute Ressource für Beispiele ist Sandcastlyles.

Wie bei allen Dingen gibt es einige wichtige Fragen zu stellen.

• Haben Sie irgendwelche Anforderungen, um Ihre Dokumentation in einem Paket zu versenden? In meinem Fall musste ich alles in einem schönen zusammengestellten Paket versenden. Sie können das mit einem Wiki nicht machen, aber Sie können das mit Sandcastle tun.
• Werden Sie die einzige Person sein, die den konzeptionellen Inhalt aktualisiert? Die meisten Wikis haben einen wirklich netten Redakteur und die Fähigkeit, schnell zwischen Themen zu verbinden. Das einzige Tool, das Sie zum Bearbeiten von Inhalten benötigen, ist ein Browser, der für einen weniger technisch versierten Schriftsteller erforderlich ist.