[ImageJ-devel] Documentation for ImageJ2

[Curtis Rueden]

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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://imagej.net/pipermail/imagej-devel/attachments/20110808/c62dde43/attachment.html>