The index tree on the left hand side at
http://docs.mitk.org/nightly-qt4/
does not look nice and contains wrongly grouped entries.
"MITK Bundle Manuals" ?
"MITK Manuals"
"MITK User Manuals" (We already have a MITK User Manual)
"Additional MITK (User) Manuals"
"MITK Additional (User) Manuals"
"Extended MITK (User) Manuals"
"MITK Extended (User) Manuals"
In the course of renaming to fix 1. one could also:
4a. Unify the module/plugin/bundle/view synonymous use to accuratly reflect the actual meaning of the word[1]. Currently they are often used incorrectly.
[1] http://docs.mitk.org/nightly-qt4/ModularizationPage.html
(In reply to comment #1)
- Considering there is already a Modules subentry called MITK Plugins how
about:
"MITK Bundle Manuals" ?
Or "MITK Plugin Manuals" ? I would like to actually converge to the term "plugin".
- I already mentioned it to the corresponding authors, but I can move them
there. So far they only contain the generated default documentation.
That is the weird thing. I thought the default generated documentation would group them correctly, and not add the docs as top-level entries.
- Few Modules that I am aware of provide any documentation and if they do
it is designed to fit into the Bundle Manuals... Maybe call 1. something
else:
My perception was that modules rarely contain sophisticated user interaction stuff where a "manual" would be needed (and if so, into which "Bundle Manual" should it go, since it could be used by several plugins?). My view is that MITK modules should only contain API documentation which is organized by Doxygen \group commands (such that it goes automatically in top-level "Modules" entry) and optionally high-level API documentation in form of Doxygen pages, which would then be sup-pages of a top-level "MITK Module Manuals" (or "MITK API Manuals", or similar).
(In reply to comment #2)
- Rename every occurence of "Module" in the bundle manuals to say "Bundle"
unless it actually IS a module (which it seldomly is, especially in the page
titles)
Yes. Actually, I would prefer to use "Plugin".
4a. Unify the module/plugin/bundle/view synonymous use to accuratly reflect
the actual meaning of the word[1]. Currently they are often used incorrectly.
Very true. "Plugin" for CTK plug-ins, "Module" for MITK shared libraries created with the MITK_CREATE_MODULE CMake macro. It is actually that simple... :-) BlueBerry Views should only appear in Plugin User Manuals as sub-entries, in my opinion.
(In reply to comment #3)
(In reply to comment #1)
- I already mentioned it to the corresponding authors, but I can move them
there. So far they only contain the generated default documentation.
That is the weird thing. I thought the default generated documentation would
group them correctly, and not add the docs as top-level entries.
By default any user manual documentation will appear at top level. It is only moved to somewhere else if it is include in another page as a \subpage, in which case it will be turned into a subentry of said page.
Unfortunately doxygen only features a "This page is my subpage move it there" command, not a "I am a subpage of that page move me there". They also will need to be moved by hand.
(In reply to comment #3)
(In reply to comment #1)
- Few Modules that I am aware of provide any documentation and if they do
it is designed to fit into the Bundle Manuals... Maybe call 1. something
else:My perception was that modules rarely contain sophisticated user interaction
stuff where a "manual" would be needed (and if so, into which "Bundle
Manual" should it go, since it could be used by several plugins?). My view
is that MITK modules should only contain API documentation which is
organized by Doxygen \group commands (such that it goes automatically in
top-level "Modules" entry) and optionally high-level API documentation in
form of Doxygen pages, which would then be sup-pages of a top-level "MITK
Module Manuals" (or "MITK API Manuals", or similar).
I just did a search, currently there are five doxygen files in all modules combined.
2 are detailing the properties introduced in that module (Planarfigure and diffusion)
1 is a headerfile with an added .dox extension, the first line is a very helpful "//copied here for documentation purposes" followed by "#ifdef DOXYGEN_SKIP" encompassing the entire file.
1 is a page detailing the capabilities of the IGT Module
1 is a tutorial on writing code using the IGT Module
The diffusion properties are linked by the diffusion bundle help. The planarfigure properties by the concept documentation on properties. The IGT stuff is the entry to the entire IGT documentation (including the plugins) [1].
So the usage scenerarios are rather mixed. I think one problem is, that for the hardware oriented modules the casual end user might in fact need no plugin at all, but only the module. This results in them actually needing real user documentation, examples and similar.
[1] http://docs.mitk.org/nightly-qt4/IGTGeneralModulePage.html
(In reply to comment #4)
Unfortunately doxygen only features a "This page is my subpage move it
there" command, not a "I am a subpage of that page move me there". They also
will need to be moved by hand.
Right, forgot about that...
(In reply to comment #5)
So the usage scenerarios are rather mixed. I think one problem is, that for
the hardware oriented modules the casual end user might in fact need no
plugin at all, but only the module. This results in them actually needing
real user documentation, examples and similar.[1] http://docs.mitk.org/nightly-qt4/IGTGeneralModulePage.html
Fully agreed. However, I think this should be separated from the "MITK Plugin Manuals" (currently named "MITK Modules") and put in that proposed additional "MITK Module Manuals" page. Having this clear separation of plugin and module documentation would be nice IMO.
(In reply to comment #7)
Fully agreed. However, I think this should be separated from the "MITK
Plugin Manuals" (currently named "MITK Modules") and put in that proposed
additional "MITK Module Manuals" page. Having this clear separation of
plugin and module documentation would be nice IMO.
While we are at it we could even consider renaming the default "Modules" page, which holds all groups into "Groups" so it can not as easily be confused with the "MITK Modules" which are something entirely different.
This should work by adjusting the layout file[2] and was supposedly fixed in this bug [3].
Considering this might end in major renaming... Is there any other name people are not happy with? Groups/Top Level entries with a wrong/misleading name?
[2] http://www.stack.nl/~dimitri/doxygen/customize.html#layout
[3] https://bugzilla.gnome.org/show_bug.cgi?id=634116
[f511e6]: Merge branch 'bug-13100-reorganize-doxygen-documentation'
2012-09-17 12:05:11 Caspar Goch [0a22c1]
renamed to layout to nondefault
[7df449]: Merge branch 'bug-13100-reorganize-doxygen-documentation'
2012-09-17 11:36:33 Caspar Goch [86a9c7]
Renamed examples doc dir Manual to UserManual
Further renaming from bundle to plugin or view, depending.
2012-09-14 19:10:22 Caspar Goch [51a8a3]
Renamed Module to plugin or view depending
2012-09-14 19:08:48 Caspar Goch [e4694e]
Added Layout file as well
2012-09-14 18:55:56 Caspar Goch [c828d8]
Changed default layout to rename Modules page to MITK API Documentation
2012-09-14 17:50:26 Caspar Goch [b7e66e]
Removed superfluous file
2012-09-14 17:47:44 Caspar Goch [778316]
Created own MITK Module Manuals page
2012-09-14 17:33:07 Caspar Goch [92508c]
Renamed modulelist to mitkpluginmanualslist and fixed text
2012-09-14 17:26:19 Caspar Goch [ba94c2]
Moved ultrasound and dicom to appropriate page