//log//

As some might know, I have been involved with the NetBeans Community Docs project for quite a while now. I have been using NetBeans IDE same way for quite a while, and I used to contribute a couple of documentation and articles on “interesting” topics to the NetBeans Community Docs project in the past. By now, however, I can’t help feeling the project slowly loosing momentum, I have a couple of vague ideas why it is this way, and even less ideas what to do about that…

Assumptions regarding community documentation…

Initially, as one might expect reading the name, “NetBeans Community Docs” was a project initiated to collect any documentation (articles, FAQs, tutorials, …) provided by NetBeans users for the sake of helping other users. This, and I still and firmly believe so, is a good idea from various points of view:

• First and foremost, it is an easy way for everyone to contribute back to an open source project without being a developer or “code hacker”.
• Then, of course, documentation provided by those who build a tool is rather different to documentation provided by those who use a tool; from that point of view the “community documentation” approach seems sane regarding the idea of gaining “user” documentation of actual use to someone as it addresses the way a potential user would see a given problem (both in terms of content and of style of documentation – thinking of “learning trail” vs. “short, to-the-point” articles).
• Last but definitely not least: Community contributed documentation, to developers and “tool makers”, seems a good thing as it exposes how end users do think and work, thus it eventually might help making a given tool better by having a better understanding for end users needs and wishes.

… and voluntary contributors in special.

Of course, community documentation doesn’t come “from out of nowhere” but has to be written by some actual contributor. And a contributor is likely to, well, contribute documentation in a given way which I quickly want to outline using an example rather familiar to me: Myself. I started using NetBeans earlier because I was searching for a quick, “intuitive”, usable IDE to do server sided / web Java development using maven2. Eclipse maven2 tooling sucked at this time (at the very least), and NetBeans came in rather handy here. In course of adopting the tool, I read some documentation, tried out a lot of things, and eventually wrote a bunch of articles on issues I stumbled across during this process… and time passed, with a few things happening:

• Generally, the IDE saw some more releases along the way, each one a little better regarding technologies I am working with, each one requiring a little less “additional” documentation than its predecessor.
• Same way, I somehow “consolidated” in my everyday work using the IDE, I finally got it working as an unobtrusive, highly productive tool not coming into my way anymore (mostly at least). The situations in which to really “hit a wall”, assuming a given solution to be worth writing an article or even a short tutorial about, are becoming less and less frequent and eventually disappear.
• And, last but not least, a bunch of things addressed in (community) documentation articles earlier by now either are addressed by the IDE itself (which has changed in some aspects to indeed be what it should be – an intuitive tool) or by “official” NetBeans documentation or it simply is “not an issue” anymore in everyday work, which makes it rather likely that community contributors won’t bother updating any “old” contributions as soon as it is not an issue to them anymore.

So, assumptions from that are that, having a “limited” set of contributors, it is rather likely to see the amount of new contributions reduce to somewhere next to Zero sooner or later, which actually might be good (as it is an expression that, overally, the tool has become convenient enough to most end-users and it allows end-users to simply and productively get their work done without bothering too much about the tool), but then again is a problem for the “community documentation” approach itself (which, as stated above, is generally a good thing).

Conclusions and ideas

How to deal with such a situation? How to resolve the problems outlined above without completely ending the project altogether? As stated, I just have a couple of vague ideas…:

• Attracting more users is an essential and important approach. Given the above assumption that “contributors” are likely to become less active as soon as they are perfectly happy working with the tool, a continuous stream of “new volunteers” addressing new areas of technology, providing new needs and wishes regarding working with the IDE or “just” running into problems no one has seen so far (because no one so far tried) seems the way to go. Is anyone using NetBeans along with, say, Python or PHP or Scala or Groovy in a production environment, or making use of its JavaFX tooling? So far, there are obviously few people on the community docs team dealing with these aspects enough to write “real-world” documentation (i.e. doing “productive everyday work” using the IDE).
• Making things more “responsive”, interactive. As soon as contributors are ready to write documentation on their own – fine. But after all, some day it might be difficult to contributors to figure out whether an issue they just stumbled across is actually worth documenting or “just” something every other user would immediately figure out taking a closer look. Maybe, from this point of view, the project itself should grow to not just be “contributor-driven” but more than that “user-driven”, allowing end-users to better state which documentation formats they like (which is surely likely to differ – i.e. /myself prefers short, to-the-point written articles on given topics and strongly dislikes screencasts and/or long, time-consuming “learning trails”) and on what issues / topics / aspects they would like to see documentation on. Maybe this also would be the way to deal with updates – a contribution being reviewed by its original contributor or someone else who is qualified enough to do so only on user demand.
• “Linking” the world together better. Using a wiki, a dedicated blog or whatever centralized structure for keeping community contributed documentation is a good idea to some extent, but then again: Isn’t a single blog entry written by someone somewhere around the world also “community contributed documentation”? Maybe taking more care of these contributions (and/or encouraging people to contribute this way) would be a way of addressing those who aren’t part of the “documentation-writing community” at the moment…

However I still think there’s quite a lot of questions unanswered, and, at this point, I see that these questions would be addressed and eventually answered best by those using NetBeans community docs… so, what are your thoughts on that? Have you ever read a NBCD article? Have you even contributed one? How did you like the project, the documentation structure, …, if you did? Share your thoughts…

Filed under: