Modularity in jME Documentation: Opinions Wanted

As I sat down and read richard_hawkes' very nice wiki entry on jME and Darkstar(he's looking for comments if you're interested int the topic) tonight, I saw something that got me thinking…



Yet again, the process of checking out from subversion was explained.  While the process in this entry was for a project that wasn't the jME trunk, I couldn't help but thinking about how many different "getting started with jME" tutorials are floating around with very similar, though slightly different, pieces in common.



I would argue that implementing a modular approach to wiki documentation could help to keep documentation efforts concentrated on the specific area of the author's expertise, as well as making the first hurdle to using jME an easier one to traverse.



An example of such modularity could be:



Welcome to my wiki article, today I'm going to show you how to use FengGUI to build a menu for your jME projects.

FengGUI is an open source project like jME, you can either download the JAR's, or checkout the source code from their repository.  If you aren't familiar with this process, you can learn to setup subversion in your respective IDE here: link to tutorial on setting up subversion goes here

Continue reading if you are building FengGUI from source.. If you are just downloading the JAR's, you may skip ahead to using FengGUI: link to beginning of FengGUI tutorial

Section: Building FengGUI

Section: Using FengGUI


That would be a simple use of such modularity.  Rather than explaining the same process over and over with a number of different tutorials, there could be one Subversion page on how to integrate it with Eclipse or Netbeans

Thoughts and criticisms are most welcome, as this was a fairly impulsive idea that just came to me

I agree. The main text of a new tutorial could just mention the big outline of steps ("get it from this svn URL", set up this or that, – advanced users already know what to do). And some paragraphs would have "if you don't know how to use subversion/how to set X up, continue here", as sbook described. I like the idea.  That way we only have to keep one tutorial up-to-date per topic.



The only catch is that everyone writing tutorials has to remember to do this.  :wink:



A similar example: I started a page where I collected all links to netbeans tutorials so I could give the links very clear names (specifying the netbeans version AND jme version it was intended for). But other people writing netbeans tutorials of course don't know of my list, so they don't add their new ones… I usually have to do that myself.



So one thing I want to mention here: It's wiki.  If you see a doc that would be helpful if it were linked somewhere else, link it!  :slight_smile:



Even if they were not written by you, a link doesn't break anything, it adds a lot of value. So next time you see somebody explaining svn again, why not add a "See also: general svn info" link. If you see a netbeans-only description and remember somebody explains the same thing for eclipse elsewhere, link to it. etc etc.



Does that make sense?

zathras said:
So one thing I want to mention here: It's wiki.  If you see a doc that would be helpful if it were linked somewhere else, link it!  :)

Even if they were not written by you, a link doesn't break anything, it adds a lot of value. So next time you see somebody explaining svn again, why not add a "See also: general svn info" link. If you see a netbeans-only description and remember somebody explains the same thing for eclipse elsewhere, link to it. etc etc.

Does that make sense?


Much sense!  I remember chuckling to myself when I saw setup instructions for Netbeans 6.5 and 6.7.1 :p