diff --git a/Documentation/Doxygen/Development.dox b/Documentation/Doxygen/Development.dox index c20b65c530..c1ddcadaec 100644 --- a/Documentation/Doxygen/Development.dox +++ b/Documentation/Doxygen/Development.dox @@ -1,30 +1,31 @@ /** \page Development Development with MITK The following items are concerned with the practical use of the MITK library for software development. Some abstract concepts of MITK are described in \ref Concepts \section DevelopmentSetup Setting Up MITK \li \subpage BuildInstructionsPage \li \subpage thirdpartylibs \section DevelopmentGettingToKnow Getting To Know MITK \li \subpage DirectoryStructurePage \li \subpage TutorialPage \section DevelopmentWith Developing With MITK \li \subpage DICOMTesting \li \subpage NewPluginPage \li \subpage StatemachineEditor \li \subpage mitkExtPointsIndex \li \subpage KnownProblemsPage \section DevelopmentContributing Contributing To MITK +\li \subpage DocumentationGuide \li \subpage StylesAndNotesPage */ diff --git a/Documentation/Doxygen/DocumentationGuide.dox b/Documentation/Doxygen/DocumentationGuide.dox new file mode 100644 index 0000000000..df0a3fa479 --- /dev/null +++ b/Documentation/Doxygen/DocumentationGuide.dox @@ -0,0 +1,47 @@ +/** +\page DocumentationGuide Writing Documentation + +\section DocumentationGuideCodeGeneral General remarks + +MITK uses Doxygen for the generation of our user manual pages as well as for the generation of the on- and offline reference manuals. So on the technical side many questions can be answered by the doxygen documentation, such as the list of commands or a few basic doxygen tutorials. + +Therefore this document is not primarily intended as a guide to using doxygen, the doxygen manual does a much better job of that, but as a guide to use doxygen in MITK and a collection of helpful hints and advise about pittfalls. + +Also, of course you need to have doxygen installed to generate documentation. + +\section DocumentationGuideCode Documenting the source code + +MITK is a substantial project and encompasses many different source files by many different developers over quite a considerable timeframe. Many of them have written excellent code which can do a lot of things and is very helpful to people who might apply it in wholly unlooked for ways for completely different problems. To facilitate this sharing and reusing of ressources one first and foremost has to know what kind of ressources are already available. + +Few people write code in the intention for it to be difficult to be used by others, but unfortunately what might seem a very efficient and easily understandable piece of code to the author might be nigh unreadable for someone else. Very often it does not in fact matter whether the code itself is understandable, as long as it one can get the information what a function is supposed to do. While comments in the source file help a lot to gain this knowledge in can get quite tedious go through every file looking for the right tool. + +This is were using doxygen pays of, by giving a short comment in the header file a reference manual is automatically generated. + +\subsection DocumentationGuideCodeHints Helpful hints: + + +\section DocumentationGuideManual Writing user manuals + +While the usage of your view/perspective/application might seem obvious and accessible to you, to most people it is not. Writing a good manual is key for this. It is very difficult to write a manual which is too comprehensive, most often if something can be done in a wrong way, somebody will see this as the only one. + +It is advisable to use a dedicated .dox file for a manual, helps keeping things clean and tidy. For MITK purposes you should put your documentation in BUNDLEPATH/documentation/UserManual/ . + +The nightly generated HTML documentation and the QtAssistant documentation can contain different content using the isHTML command. + +\subsection DocumentationGuideManualHints Helpful hints: + + +*/ +