[ImageJ-devel] Documentation for ImageJ2

[Adam Fraser]

CellProfiler modules have a nice way of documenting themselves to the point
where they can document each parameter that the user can fiddle with.
Formatting is done in via HTML, which I think is pretty common. This
documentation can be accessed from within the program itself and it can be
used to generate a doc.

-Adam

On Mon, Aug 8, 2011 at 4:31 PM, Curtis Rueden <ctrueden at wisc.edu> wrote:

> Hi Tiago,
>
> Thanks very much for pushing the documentation issue, and sorry for the
> long delay in my reply.
>
>
> - Which plans do you have for the IJ2 documentation?
>>
>
> There will be an increasing focus on documentation during the three-month
> beta period later this fall. For now we are still pushing to make everything
> work as it should.
>
>
> - Could the guide be extended to ImageJ2? (A new chapter?) Or should it
>> cease
>>  with 1.45 and a new one be written for IJ2? In which modality then?
>>
>
> I agree with Gabriel that perhaps many parts of the guide will be directly
> applicable to IJ2, at least temporarily, but it will definitely need major
> updates.
>
>
> _ I think self-contained user documentation is very important. I know some
>> of
>>  you would prefer a wiki-like user guide. My experience however tells me
>>  that average lay users don't. My opinion is that self-contained documents
>>  are key to non-power users and wikis best suitable for advance usage and
>>  How-Tos.
>>
>
> I think this is an important observation. What I would like to see is the
> best of both worlds: exposing the online wiki documentation from within the
> software itself, as built-in help. I also agree with your goal of creating a
> system that can generate a self-contained document such as a PDF. We will be
> in touch with you more later about deploying that system for IJ2. And we
> will certainly be able to help you with the actual documentation effort,
> when the time comes.
>
>
> - It would be great if IJ2 users had more visible access to documentation.
>>  Something like Fiji's "Help on Menu Item" would be great.
>>
>
> Right. Except that we will need to be more diligent about documenting every
> command.
>
> Another possibility is for the plugins themselves to allow for
> self-documentation. We have this a bit already with a "description" field
> for every input parameter, as well as for the plugin itself, but it could
> perhaps be fleshed out more. Also might be good to add a URL link field.
>
>
> - BTW, from a strictly usage point of view, IJ has some big flaws (e.g.,
>> the
>>  notorious interpretation of binary images via the blackBackground
>> option).
>>  It would be great if IJ2 featured more user-friendliness.
>>
>
> Well, we will do what we can, but people tend to disagree on what is
> "friendly." In the case of the black background option, we plan to eliminate
> that option. If you want things to look inverted, you can just invert the
> LUT. But maybe there will be some complaints about it—we'll see. Another
> example is RGB color vs. 3-channel 8-bit unsigned integer composite images:
> they display the same and are fairly redundant, so we are eliminating the
> RGB color mode, except for legacy purposes.
>
> -Curtis
>
>
> On Sun, Jun 5, 2011 at 9:57 PM, Tiago Ferreira <
> tiago.ferreira at mail.mcgill.ca> wrote:
>
>> Hi,
>>
>> I'm also very excited to see the 3rd alpha released.
>> I imagine that with so much to do, user documentation is probably the last
>> thing you want to think about right now but nevertheless I would like to
>> raise this issue here.
>>
>> I've been working on a new revision of the ImageJ Guide. I've been
>> struggling
>> to create a "publishing system" that could output simultaneously PDF, HTML
>> and booklet versions. It is far from perfect but its getting there.
>> A working draft is here (it is rather slow on dropbox):
>>
>>           <http://dl.dropbox.com/u/136719/guide/index.html>
>>
>> It would great if it could be extended to ImageJ2, but I would need
>> guidance.
>> I've just compiled IJ2 on my laptop and felt overwhelmed only by skimming
>> some source files. Documenting IJ1 was hard, documenting IJ2 seems already
>> impossible, but Johannes seems to think it is doable :)
>>
>> Questions:
>> - Which plans do you have for the IJ2 documentation?
>> - Could the guide be extended to ImageJ2? (A new chapter?) Or should it
>> cease
>>  with 1.45 and a new one be written for IJ2? In which modality then?
>>
>> Suggestions/Comments:
>> _ I think self-contained user documentation is very important. I know some
>> of
>>  you would prefer a wiki-like user guide. My experience however tells me
>>  that average lay users don't. My opinion is that self-contained documents
>>  are key to non-power users and wikis best suitable for advance usage and
>>  How-Tos.
>>
>> - It would be great if IJ2 users had more visible access to documentation.
>>  Something like Fiji's "Help on Menu Item" would be great.
>>
>> - BTW, from a strictly usage point of view, IJ has some big flaws (e.g.,
>> the
>>  notorious interpretation of binary images via the blackBackground
>> option).
>>  It would be great if IJ2 featured more user-friendliness.
>>
>> Best,
>>
>> -tiago
>> _______________________________________________
>> ImageJ-devel mailing list
>> ImageJ-devel at imagejdev.org
>> http://imagejdev.org/mailman/listinfo/imagej-devel
>>
>
>
> _______________________________________________
> ImageJ-devel mailing list
> ImageJ-devel at imagejdev.org
> http://imagejdev.org/mailman/listinfo/imagej-devel
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://imagej.net/pipermail/imagej-devel/attachments/20110808/437437b0/attachment.html>