X

Geertjan's Blog

  • September 30, 2005

Why Plug-in Module Development in NetBeans 5.0 Sucks..

Geertjan Wielenga
Product Manager
...for technical writers. Normally, when you're writing help topics, you try to decide what the tasks are that the user will want to do. And then you create a help topic for each task. And then you write the steps for each help topic. You try and make things as simple as possible, with as few steps as possible—but enough steps to make the task taskworthy. Everything should always be clear, concise, and correct. However, plug-in module development in NetBeans 5.0 is so "good", that many of the most crucial tasks consist of only one step. This is really annoying, if you're a technical writer. (Also because you feel a little bit obsolete.) Writing tasks with one step is kind of weird (some writers cheat and break one step into two, which also looks weird).

For example, here are some topics I'd like to write for plug-in modules:

  • Create an NBM File
  • Install a Module
  • Reload a Module

And here are some of my topics for applications built on top of the NetBeans Platform:

  • Build a ZIP Distribution
  • Build a JNLP Application
  • Run a JNLP Application

But, firstly, here's all you need to do to create an NBM file (an NBM file is a binary of your plug-in, which can be installed via the Update Center):

And then stuff happens in the background and two seconds later you have an NBM file (which you can immediately install via the Update Center):

Secondly, here's what you do to run a JNLP application (read Deploying Software with JNLP and Java Web Start for details on JNLP):

And then lots of stuff happens in the background, and six seconds later your JNLP application is run:

So do you see the problem? One step! All of the tasks listed above consist of one tiny little step. So, if you see topics that take three steps to do what should really be done in one, providing silly instructions like this...

  1. Open the Projects window (Ctrl-Shift-1).
  2. Right-click the module project node.
  3. Choose Create NBM.

...instead of this...

  1. Open the Projects window (Ctrl-Shift-1), right-click the module project node, and choose Create NBM.

...then you'll know that I tried, I really tried...

Join the discussion

Comments ( 4 )
  • james hoskins Friday, October 14, 2005
    I have a question that might take more than one step to answer. I would like to modify the netbeans editor so that it provides syntax highlighting, code completion and page folding for ruby. As far as I can see, this is not a one step problem.
  • Geertjan Thursday, November 24, 2005
    True. But, tutorials will show you the way. Here , for example, is the syntax highlighting tutorial. Feedback welcome!
  • Michael Sunday, February 19, 2006
    We have an evolution in the nature of tutorials (aye, software development itself):
    • a movement from procedural-based instructions (step 1, step 2, step 3... which definitely sounds like something that can be automated to me!)
    • and moving towards a "context-based" exposition / explanation... as in: What the hell is a NBM? Update Center, who? Why would I want to create a JNLP application?

    These "new" types of tutorials teach, rather than enumerate; they give perspective, so that the reader can make a choice about if they want to do that "one step", or not. That's the kinda stuff a computer can't decide so easily, and can't be automated. Unfortuntely, "plugins" / wizards / et al take much of the "thinking" and "knowing" out of the development process, reducing it to "doing" (clicking without thinking), perhaps misleading people into believing that now software development is easier than ever (click, and voila!), when in actuality it's harder than ever. (What is it, exactly, that I want/need to do, and why? Too many options, possibilities, pro's and con's...)
  • Michael Sunday, February 19, 2006
    Btw, you really should obfuscate the email addresses (the mailto:'s) in the comments. at least change the mailto: href to not include the "@". Or mark "E-Mail" field as optional in the comments and/or with a warning note!
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.Captcha