Structuring IJ Developer Wiki

This topic should be about discussing the (re-)structuring of the imagej.net wiki page in relation to the developer part of the page. Final aim is to get a clearly structured step-by-step guide for plugin developer newbies in how to start writing their plugins in the ImageJ2 code structure.
If this should rather be discussed on an IJ guide gitter channel or so, let me know to migrate it there.

Many of these things might be very clear to experienced programmers, but for newcomers I think it is difficult to see the clear path from their initial idea to their final running plugin in “virtual brain code” so far.

This should not be a critisism on all the immense amount of already existing information but rather a starting point for things to add in the future. Actually, the revised version of http://imagej.net/Development looks nicely structured. What I will mention below would now fit to the final point and there actual to the “Writing ImageJ2 Plugins” part.

This should include for example some statements on the changes regarding some term definitions (which currently still confuses me) and the sequence to follow starting learning IJ2-programming from scratch. Advanced users still can skip individual sections which they consider too basic.
Here some loose ideas for the moment (I might have missed an existing explanation for what I am listing here, but this would show that it might not be obviously accessable):

  • why is a plugin now called a command and what kind of command do actually exist (something which is somehow partially digged in the the javadocs, but you need to find and cherry-pick it).
  • why do we now have Services and how can the functionality of a service be perceived best from a beginners point of view.
  • adding an example tutorial on how do I implement/use a Service (if not already existing).
  • what are all the possible annotations (potentially including their parameters, but this can actually also be looked up in
  • generally it gets more complicated, because the programmer might need to work with different Javadocs. So, when do I need which JavaDoc and with which information should I start best if I have no clue? This is a little bit like the structure from Christian in the hackathon doc.
  • a sorted list of the links to the existing tutorials on git which then still needs to be updated with additional tutorials (also some even more basic ones, I’ll try to create some on my way learning this)

So, I hope I didn’t just list things which are already existing and I am just too clumpsy to find and assemble them. If so, ignore my topic and bash me with those URIs :wink:

2 Likes

Additional introductory info for setting up EGit for newbies (which are still not familiar with the command line) in Eclipse and some helpful videos working with Git from Eclipse:

You need to first install EGit as an extension (from this page: http://download.eclipse.org/egit/updates)

here is a video tutorial how to do that and an intro on how to clone a public repo: https://www.youtube.com/watch?v=ptK9-CNms98

If we are talking about a Maven project I figured out that after cloning the repo into your local git folder you simply import them into the package explorer (navigator) (in the former video approx. at time 3:00). Thereafter, (unlike in the video) you do not delete the project in Eclipse, but right-click the respective Git repository entry in the Gitr panel of Eclipse and select >Configure >Convert to Maven Project.
Et voila, ready and all in Eclipse. I don’t know if this would have any disadvantages over cloning it via command line and then importing the maven project, but so far, I couldn’t detect any.

Furthermore, you will find helpful how-to info for branching, staging, committing, pull- and push actions and merging repos in the following videos which, when watched in sequence were really helpful to me.

1.) https://www.youtube.com/watch?v=C0bFLGJqnI8 (I skipped that one)
2.) https://www.youtube.com/watch?v=r5C6yXNaSGo
3.) https://www.youtube.com/watch?v=V42r5REJx-M
4.) https://www.youtube.com/watch?v=rblGZRWqFVI
5.) https://www.youtube.com/watch?v=qhd3HB6-1K8

Surely, command line is for many things more flexible with all the attributes you can use for the commands, but it is easier for the beginning if starting without commandline experience.

Another nice page (rather for commandline usage, but makes the ralations between the differen levels clear):
http://ndpsoftware.com/git-cheatsheet.html

I agree with you.
Something which I would appreciate is some kind of a checklist like described here:

This would help me a lot.

Maybe such a checklist can be extended to more then just imagej-ops.

1 Like

I very much agree with this, not just from an documentation standpoint, but it also forces us to clearly write out the intentions, paradigms and reasons behind the design of the software.

There should be a checklist for every one of the common operations (e.g. pull requests, unit tests, …).

Great, I’m glad things are getting better. I personally am really excited about the recent edits we have been doing to make the wiki more approachable from the toplevel, for both user and developer topics. More still in the works, especially in the Development section.

That would indeed be fabulous. Ideally it should be similar to the ImgLib2 Examples page in that the prose would embed code snippets which match what is in the linked Git repository.

We already have the imagej-tutorials. It just needs to be restructured a bit: divided into numbered intro topics, and then more specialized later topics.

After talking to @etadobson, we are trying to deemphasize all the ImageJ1 comparisons. We can still have some when it is especially useful, but we think the “from scratch” angle is most useful long term. For those who already know ImageJ1, reading about how IJ2 works “from scratch” is probably still OK in most cases.

The current explanation is in the What is a plugin? section of the Writing plugins page.

The gist is that a “plugin” in SciJava terms is now incredibly general. We needed a word for the Runnable plugin type (similar to ij.plugin.PlugIn in IJ1), and Command seemed best since they typically go into the menus, and ImageJ1 already refers to menu entries as “commands” (e.g., the Command Finder).

If that explanation is not clear enough, ask away and I will clarify further. (That goes for everything on the wiki! :sunny:)

What we have so far is at Services in SciJava Common on the wiki.

What we have so far is at Writing a service in the Writing plugins page.

There are only @Plugin and @Parameter right now, at least in the core system. Both of those are covered in the tutorials.

There is http://search.imagej.net/ with the Javadoc button, to help you with that.

The javadocs at http://javadoc.imagej.net/ also do cross-link to one another whenever possible. While we could produce one huge “All” page that has everything, I think it would be pretty overwhelming.

A sorted list like Category:Tutorials? I think it fits the bill. We just need a wiki page per tutorial on GitHub.

Sure, I cited some links above, but A) they could all use improvement; and B) the fact that you couldn’t find them means we need better organization and linking. Things are improving, but still more to be done. Maybe you see places you can inject some of those links/tips, and want to make some wiki edits?

If you install the Eclipse IDE for Java developers, EGit comes preinstalled. It should even automatically link your projects now, so you don’t have to choose Team :arrow_forward: Share anymore from the context menu.

So this documentation should only be a matter of understanding the right-click context menu’s Team, Compare With and Replace With submenus.

The reason no one has written that documentation is because none of the core ImageJ developers use EGit that way—we all prefer command line Git. If there is anyone out there who does use EGit for these things, contributing docs to the wiki (perhaps on the Eclipse page?) would be awesome.

Nice. These links could make a nice new page on the wiki. The current Git pages are all command-line-focused, and generally in need of updates.

Thanks Curtis for answering so detailed.
I am well aware of many of the links you mentioned and just think some more detailed info added will make it even more awsome :sunny:

exactly what I intended to express :slight_smile:

got this and potentially this is helpful to add in a small part (or even a small separate page for annotations with some additional ones which might be helpful)

True. The javadoc overview page is just great (helped me a lot in the last days). Nevertheless, for the “Intro to IJ2 plugin Development” section, or should we better call it “IJ2 Command Development” (?), it would be helpful to have also an initial sequence on what to read first and then after or a small example on something like,…for which types of command do I need mostly which documentation.
I don’t know if such an example would make sense but a beginner is (as you said) overwhelmed by looking at SciJava, ImageJ-JavaDoc, ImgLib2, Ops ,… at once (and might be lost). At least that is how I still feal at the moment (being a “beginner” in that sense).

This is most likely the best idea tackeling this issue!

will definitely do so :smile:

in my case the full EGit support was not preinstalled (using Eclipse Mars)

I am well aware that most use the command line (which is awsome if you can do that). For me personally the EGit is a quite nice (even though maybe rudimentary) alternative, so far.
I will start a new section on the Git page deviding it into command line and EGit part (if that would be ok for you guys?).

If I may add my two cents to this: I had started learning git by using it from the command line as explained on the wiki pages, but now I am quite happy using SourceTree: It has a nice branch view, and you can do almost everything (pull, push, interactive rebase, …) from the user interface.

thanks for adding this link. I included this directly in the new http://imagej.net/EGit section and I am happy about comments or suggestions to extend this.

Question from my side… can I (and if, how) change the {{Git}} template page somehow to add this section in the list ?

Found it, sorry for bothering :blush:

Forgot this beforehand:
This is an awsome, simple explanation which everybody will understand :sunny: . I would add those kind of small explanations in the tutorials to make new things clearly understandable.

1 Like

Great. Then today I will work on restructuring the tutorials and adding wiki pages along those lines.

How about “Writing plugins” for the top-level thing, which is a general intro to what plugins are in IJ2, with links to tutorials about specific types such as “Writing commands”, “Writing ops”, “Writing services”, etc.?

I will do it like that for the initial restructuring today, and we can go from there. I want to avoid plastering the term “ImageJ2” everywhere now, since it will look increasingly strange as time goes on.

The whole wiki now assumes you are using ImageJ2—that’s what the Downloads page gives you, after all. Those who want info focused on ImageJ 1.x can use the ImageJ 1.x website at http://imagej.net/index.html.

Of course, we can still have brief comparisons between IJ1 and IJ2 to avoid massive confusion, as needed. But we definitely do not want new people feeling like they somehow need to know about IJ1 before they can learn IJ2.

Awesome, thank you for all your efforts!

That is really strange. According to the Eclipse features matrix it should be preinstalled in nearly every flavor of Eclipse Mars. So we should test things a bit further, then. We want to avoid superfluous (for most people) documentation being distractingly front and center. Maybe in this case we just want a simple link pointing to the EGit docs, rather than a point-by-point guide? But even that worries me, since it implies the installation is more complex than it is supposed to be.

The new page looks great! :guitar: And I like the Git menu template update, with the horizontal bar. It really highlights the first couple of guides as most important. We could use that same trick in other menus, too.

OK! Would you care to edit What is a plugin? to read more clearly for you?

I will check this installation stuff out again. I also did not plan to add more guides to the EGit page, since the videos are fairly well self-explanatory.

I will take care of that, but that might take a bit until I myself catch all the necessary knowledge to explain it to others :blush:

Uff, thanks god. I was not sure if I should mess around with the template. In general to the templates… If you guys don’t want that they are updated by everybody please let me know. I just thought separating the two introductory and UI-Git part from the commandline part would make sense (was not ment to give it a weighting).

These templates are awesome to use them for the user guide as well. This will make the look more uniform, which I think demonstrates some consistency and might be important for one or the other user.

Please do. The LOCI team cannot sustain our current level of wiki-editing for too long before being pulled to other things. The more people who know about and improve the templates, the better. If worried about your changes, use the “What links here” feature to double check how the template renders in existing pages.

Indeed!

By the way, I noticed your use of @tferr’s Bc template (what does Bc stand for?). That is an awesome template! I wish I had known about it a couple of weeks ago when I made the Arrow template which is less good. I will try to batch update the wiki to stop using {{arrow}} in favor of {{bc}}…

Bc is an acronym that in tferrian language stands for Breadcrumb… Looking back is not that intuitive, but I think I got the idea from the libreoffice wiki (I may be wrong, it has been a while)…

This topic is now a banner. It will appear at the top of every page until it is dismissed by the user.

This topic is no longer a banner. It will no longer appear at the top of every page.

OK, I did it. The {{bc}} template is unstoppable now!

1 Like

I would suggest, that we don’t reproduce a full “Java Beginners + IDEs+ Git + Maven” in the ImageJ2 Wiki. We should point on some resources, but imagej.net should focus on the documentation of its own technology, because someone has to maintain and structure everything. Maybe a quick guide: Requirements are Git(-Hub), Maven and how to get the stuff into Eclipse.

1 Like

Agreed. However, there is a lot of existing material on Git and Maven, which I am a little reluctant to edit down. Maybe someone else wants to take a crack at it? I feel like I’m “too close” to those technologies to do a good job.

My two cents as a ‘newbie’: all that information already on the wiki - needs to stay on the wiki. It is important for new users to read and understand… And it’s already written - so no need to remove it (for sure - not necessary to add to it at this point). All efforts now are in restructuring that information to better direct those new users to the most pertinent information - always with respect to ImageJ. That is where efforts are needed now - and are currently being directed…

agreed. just saying: new contents should be added if they are adding new value and not reproduce some information which already can be found somewhere in the internet (especially, more general stuff like java, maven, git etc).

1 Like