[Insight-users] updating softwareguide ?
Luis Ibanez
luis.ibanez at kitware.com
Wed Jul 1 12:38:09 EDT 2009
Hi Michael,
Thanks for this detailed description.
As you pointed out,
it is important to provide more context on how to use methods for a class.
We find easier to do this in the Examples, than in the Doxygen
documentation,
but it clearly could be done in both.
You point out as well that a lot more of cross-referencing could be helpful.
The PDF version of the Software Guide, has hyperlinks to the Doxygen
documentation, but not the other way around.
It will be nice if the Doxygen documentation pointed out to sections of
the Software Guide (we will have to come up with a maintainable system
of links... preferably fully automatic...).
Clarifying what should be the order of method calls is very important.
This is commonly overlooked and a becomes a common cause of
frustration. Developers tend to be aware of the "order dependencies"
and forget to make them explicit in the documentation.
All in all, we should find a channel for gathering the collective wisdom
and experience of the ITK community, in such a way that users can
get quickly to functional examples of code, sets of parameters and
example images.
Luis
--------------------------------------------------------------------------------------------------
On Wed, Jul 1, 2009 at 7:59 AM, Michael Schildt <
michael.schildt at ifn-magdeburg.de> wrote:
> Hello all,
>
> This SoftwareGuide is a good starting point. Even if it is outdated
> somehow. And some kind of semiautomatic update would be great.
> But i would like to point out an issue with ITK documentation. A lot of
> information is available for ITK (Insight into images book,
> ItkSoftwareGuide, Doxygen documentation, Wiki, examples, Insight Journal,
> Mailing List). This is very impressive and should be enough. I use all of
> them and still struggle with trivial problems from time to time. Basically,
> by missing hidden but existing dependencies or wrong understanding of what a
> function does.
> It is from my point of view impossible to figure out dependencies of
> function calls with the Doxygen generated documentation. For example often
> an implicit order for functions calls of an object is assumed. When you take
> an example from ITK and copy/paste it in your application it normally runs.
> If you change some component then at least for me something goes wrong
> often. A good documentation example is
> http://www.itk.org/Doxygen314/html/classitk_1_1MatrixOffsetTransformBase.html#dbafaf9635750c1b0e204c52deb1de46
> It tells you what you have to set next and names an alternative. It gives
> me important context information.
> But documentation like
> http://www.itk.org/Doxygen314/html/classitk_1_1MatrixOffsetTransformBase.html#bab57111fda06e69309c80fdf6fbee38
> is useless if i don't know what fixed parameters are. No link to releated
> functions or concepts. I can find this information somewhere else, but
> typically for a beginner it is not easy to find this information. I guess,
> it would be of great benefit to include some more information or links to
> the right place in doxygen generated documentation. I know it will be
> redundant, but typically you have a concrete problem and look for it at the
> expected position in the documentation.
>
> The examples of ITK are a good starting point too and are documented in the
> Guide and tells what is allowed and possible with ITK. Maybe it would be a
> good place to tell what is not allowed, what is not possible, where a
> certain order of function calls is required. That could probably reduce the
> amount of posts in the mailing list.
>
> Or is it the way i am working with ITK?
> 1) I make myself clear off the problem i want to solve.
> 2) I look for an example in the itkSoftwareGuide
> 3) If not found there i look in the example folder or the application
> folder
> 4) look for the things i need to change in the examples to solve my problem
> 5) look in the Doxygen generated documentation for the description of
> function which are not clear to me or look for alternatives needed for my
> problem (often not satisfying)
> 6) If neccessary look up in the Insight into Images book for description of
> concepts
> 7) put things together, compile, execute and sometimes run into unexpected
> issues
> 8) debug, use google to search mailing list and try to fix
> 9) realize there must be something else, not mentioned in the docu
> 10) use mailing list and hope for willing itk-users to help me out, which
> most of the time is happening :)
> Is there another (maybe more efficient) way to use ITK?
>
> Best reguards,
> Michael Schildt
>
> Darren Weber schrieb:
>
>>
>> It seems that a lot of the software guide is coded in the examples, using
>> comments in the example .cxx src. Perhaps contributors for new classes can
>> develop simple examples with similar comments for inclusion in a regular
>> build for the software guide, to provide some degree of updating for the
>> guide. It's fairly simple latex text in the comments. I know most everyone
>> has learned M$ Word these days, but I would imagine latex is still prevalent
>> among the math and comp-sci community. The advantage to this is that the
>> examples can be compiled and distributed with the src code, while the wiki
>> is not.
>>
>> Take care,
>> Darren
>>
>>
>>
>> On Tue, Jun 30, 2009 at 10:04 PM, asamwm <asamwm at gmail.com <mailto:
>> asamwm at gmail.com>> wrote:
>>
>> Hi Luis,
>> since this is all in the spirit of open source community,
>> part of whose growth is credited to people from the
>> community, why not create agree on an architecture
>> for community-based documentation where everyone
>> who participates in developing/evaluating/using a filter
>> can contribute to the wiki. The journal is a stepping
>> stone but the more detailed, elaborated documentation
>> would be the wiki.
>> There would be fixed sections such as:
>> general purpose (what problem it attacks, image examples)
>> advantages / why this one ,
>> known disadvantages (why not),
>> how it works (optimization),
>> same category as in (list of other filters)
>> see also (broader area)
>> code snippets
>> pitfalls
>>
>>
>> I know one concern is to be careful not to misinform,
>> but this is the beauty of open source. The community
>> will correct falsehoods with time. Besides, this does
>> not need to replace the itksoftwareguide since
>> that one is specific to the basics.
>>
>> Just my 2c.
>> I do not know how everyone feels about this.
>> Please share.
>> Regards.
>>
>>
>> On Tue, Jun 30, 2009 at 3:06 PM, Luis Ibanez
>> <luis.ibanez at kitware.com <mailto:luis.ibanez at kitware.com>> wrote:
>>
>>
>>
>> Hi Oliver,
>>
>>
>>
>> 1) Yes, the ITK Software Guide is overdue for an update.
>>
>>
>> 2) You can see a manifesto of new filters on the Wiki
>> page of every release.
>>
>> For example:
>>
>> http://www.itk.org/Wiki/ITK_Release_3.14
>> http://www.itk.org/Wiki/ITK_Release_3.12
>> http://www.itk.org/Wiki/ITK_Release_3.10
>> ....
>>
>>
>> 3) Yes, the ITK Software Guide will be updated,
>> probably in the next year or two.
>>
>>
>> 4) Since 2006, All new classes in ITK must have been
>> described in Insight Journal papers.
>>
>> If you need information about a New class,
>> there must be a paper in the Insight Journal
>> describing this class.
>>
>>
>> For example, the Chan and Vese level set filters
>> are described in
>>
>> http://www.midasjournal.org/browse/publication/322
>>
>>
>>
>>
>> Regards,
>>
>>
>> Luis
>>
>>
>> ----------------
>> Oliver Gloger wrote:
>>
>> Hello together,
>>
>> Is it true that the SoftwareGuide did not change since
>> 2005? On the other hand I can see from the mailing-list
>> that there exist new filters now (i.e.
>> itkScalarChanAndVeseSparseLevelSetImageFilter or other
>> filters, which are not mentioned in the ITKSoftwareGuide).
>> Will the ITKSoftwareGuide be updated? Where can I be
>> informed about how to use new adjoined classes and filters
>> in the ITK?
>>
>> best regards
>> Oliver!
>>
>>
>>
>> _____________________________________
>> Powered by www.kitware.com <http://www.kitware.com>
>>
>> Visit other Kitware open-source projects at
>> http://www.kitware.com/opensource/opensource.html
>>
>> Please keep messages on-topic and check the ITK FAQ at:
>> http://www.itk.org/Wiki/ITK_FAQ
>>
>> Follow this link to subscribe/unsubscribe:
>> http://www.itk.org/mailman/listinfo/insight-users
>>
>>
>>
>> _____________________________________
>> Powered by www.kitware.com <http://www.kitware.com>
>>
>> Visit other Kitware open-source projects at
>> http://www.kitware.com/opensource/opensource.html
>>
>> Please keep messages on-topic and check the ITK FAQ at:
>> http://www.itk.org/Wiki/ITK_FAQ
>>
>> Follow this link to subscribe/unsubscribe:
>> http://www.itk.org/mailman/listinfo/insight-users
>>
>>
>> ------------------------------------------------------------------------
>>
>> _____________________________________
>> Powered by www.kitware.com
>>
>> Visit other Kitware open-source projects at
>> http://www.kitware.com/opensource/opensource.html
>>
>> Please keep messages on-topic and check the ITK FAQ at:
>> http://www.itk.org/Wiki/ITK_FAQ
>>
>> Follow this link to subscribe/unsubscribe:
>> http://www.itk.org/mailman/listinfo/insight-users
>>
>>
> _____________________________________
> Powered by www.kitware.com
>
> Visit other Kitware open-source projects at
> http://www.kitware.com/opensource/opensource.html
>
> Please keep messages on-topic and check the ITK FAQ at:
> http://www.itk.org/Wiki/ITK_FAQ
>
> Follow this link to subscribe/unsubscribe:
> http://www.itk.org/mailman/listinfo/insight-users
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.itk.org/pipermail/insight-users/attachments/20090701/8fa6acd8/attachment.htm>
More information about the Insight-users
mailing list