Online Reference Manual

Is there a copy of the VASSAL reference manual online on the vassalengine site that we can link to from the wiki?

Brent.

Not one that’s up to date anyway. A great thing to do would be to upload the reference manual as part of a build, but it hasn’t been done.

rk

Post generated using Mail2Forum (mail2forum.com)

Thus spake “Rodney Kinney”:

Also, I think it would be useful to have the javadoc online. That might
encourage people to help us.


J.


Messages mailing list
Messages@forums.vassalengine.org
forums.vassalengine.org/mailman/ … engine.org

Post generated using Mail2Forum (mail2forum.com)

What we really need is a volunteer/s to step forward and take the entire Help/Documentation task under their wing. I feel the only way to find people like this is to spread Vassal’s reputation, attract more people to the forum and hopefully find more dedicated individuals such as we have in the Development team at the moment.

I don’t think we have the resources to do anything other than talk about effective documentation at this point in time.

Thus spake “bsmith”:

I agree. Many large projects out there have volunteers who maintain
docs and websites. (Look at any Linux distribution—there are hordes
of people doing this sort of thing. We really only need one or two.)

Volunteering to maintain documentation is maybe the single most
important way that non-coders could help improve VASSAL. Not only
does good documentation make VASSAL more accessible, but it’s also
a more efficient division of labor. Time spent by developers writing
non-technical documentation is time not spent fixing bugs and adding
features.


J.


Messages mailing list
Messages@forums.vassalengine.org
forums.vassalengine.org/mailman/ … engine.org

Post generated using Mail2Forum (mail2forum.com)

As non-coder, I’d love to help with documentation! I’ve never coordinated a documentation project/effort before, but I’d like to think I could learn to do so quickly if no-one else steps forward. Also, I’m not an expert VASSAL user yet (which is to say I haven’t tried designing or editing a module) but I should have that rectified soon.

That’s awesome meng, thanks!

OK, I think the priority right now is to concentrate entirely on players new to Vassal. In particular:

  • The installation process including module download and where to save module files etc.
  • Advise them to know the rules to the game they want to play before tackling Vassal for the first time; This is a common newbie mistake which leads to some becoming overwhelmed.
  • When they first open a module explain how they should familiarise themselves. This includes knowing where all maps and charts are located.
  • Tell them to look at the different game counters. They should drag a few to the map and become familiar with the right-click features of each piece. They should also play with a few of the shortcut keystrokes.
  • Explain how some games have simultaneous-reveal mechanisms and how to handle them using both PBEM and Live play.

This documentation should be hosted on vassalengine.org in html format. I think we should avoid including any docs with the distribution, this seems to be the way the big-boys are heading these days; We can safely assume that 95% of users have full Internet access. It means we can more easily keep it up-to-date. There’s probably no need to version control it either; Keep it simple.

But most important of all meng, bombard us with stupid questions! We should assume we are creating documentation to teach our PARENTS how to use Vassal! It’s a safe way to make sure we are explaining things as clearly as possible.

:laughing:

This is sort of layout we should be aiming for in the long-term; Two frames with a hierarchial index.

http://help.eclipse.org/help33/index.jsp

But because we only have only one documentation guy at the moment, just something up-to-date is a good start!

How are your html skills meng?

I would still like to see the current reference manual that is downloaded with Vassal available on-line. This seems a no-brainer to me - very little work required.

*********** REPLY SEPARATOR ***********

On 14/01/2008 at 10:06 PM bsmith wrote:


Brent Easton
Analyst/Programmer
University of Western Sydney
Email: b.easton@uws.edu.au


Messages mailing list
Messages@forums.vassalengine.org
forums.vassalengine.org/mailman/ … engine.org

Post generated using Mail2Forum (mail2forum.com)

Thus spake “bsmith”:

I use my laptop on planes, on trains, and outdoors. I don’t have Internet
access there. Sometimes my DSL is down. I doubt that I’m alone in these.
I think we should include the same docs with VASSAL as we put on the web.

Second, I really would like it if we could keep the docs under version
control. Firstly, that makes them easy to package, and second it prevents
data loss.


J.


Messages mailing list
Messages@forums.vassalengine.org
forums.vassalengine.org/mailman/ … engine.org

Post generated using Mail2Forum (mail2forum.com)

Thus spake “bsmith”:

Do you really find the left frame useful? I usually hide those, because
I can’t ever seem to find what I want in them. The Java JDK docs are
even worse in this regard, because if you have the index pane visible,
then when you search you have to cycle through it when where you really
want to look is the right pane.


J.


Messages mailing list
Messages@forums.vassalengine.org
forums.vassalengine.org/mailman/ … engine.org

Post generated using Mail2Forum (mail2forum.com)

Including the docs with releases, and storing them in version control would mean we are assuming the development team is happy to spend a bucketload of time helping out the documentation crew.

Remember these guys will not be programmers, they’re not going to know the first thing about version control and nor should we expect them to. I would suggest we give them FTP access so they can just manage html pages, and Rodney can make sure it’s backed up; It’s a simple and easy solution which means we will have what we need quickly, and the doc guys only need to learn basic html.

I believe if we put them into SVN, no-one who isn’t a developer will update them, and we’re back at square one. Too much complexity for something we just need to have at this point.

I think they’re probably more useful for some than others. We, as geeks, know how to do an effective text search; But some users just know how to click accurately. I’m assuming we’re dealing with complete newbs here.

On Tue, January 15, 2008 10:25 am, bsmith wrote:

WebDAV and auto-commit? I’m not sure if this is feasible or not, I’m
quite new to SVN, but it seemed quite a neat feature. I think that if
you’re targetting non-programmers to help with docs, the ability to
connect to a ‘web folder’ is a more common skill these days than to drive
FTP.

I might also be in a position to help with the docs - I don’t have a
concrete enough time commitment to lead the work, but I’ll have a look at
the to-do list once we have one. (Technical documentation for the
less-technical-than-me is a good slice of $DAYJOB).

Cheers,
Tim.


Messages mailing list
Messages@forums.vassalengine.org
forums.vassalengine.org/mailman/ … engine.org

Post generated using Mail2Forum (mail2forum.com)

Your likely right about FTP Tim, probably better ways. maybe we should wait to hear from Meng, see if he has any skills in this regard.

Thus spake “bsmith”:

What’s wrong with teaching people how to use SVN? I know quite a few
non-programmers who use SVN, several of whom I’ve taught myself. They’re
uniformly glad they learned how to use it. (I hear that TortoiseSVN is
a nice stand-alone client.)

Alternately, if we had a decent wiki (like MediaWiki) we’d get the
benefits of version control without the complexity, and could produce
static docs for distribution with VASSAL with a wiki dump.

An aside: It never ceases to amaze me that the two of us disagree on
virtualy everything. I don’t set out to be contrary, really I don’t!


J.


Messages mailing list
Messages@forums.vassalengine.org
forums.vassalengine.org/mailman/ … engine.org

Post generated using Mail2Forum (mail2forum.com)

Thus spake “bsmith”:

Do people seriously try to navigate documents without search? Wouldn’t
it be better to educate people how to search effectively?

As they say, “Build a man a fire and he’ll be warm for a few hours,
set a man on fire and he’ll be warm for the rest of his life.”


J.


Messages mailing list
Messages@forums.vassalengine.org
forums.vassalengine.org/mailman/ … engine.org

Post generated using Mail2Forum (mail2forum.com)

1 Like

I agree. For windows users, TortoiseSVN is so simple, anyone can use it. It integrates into Windows so you can just right-click on a file and select Commit. It adds an icon to the folders to show which are up-to-date and which have changed. If the doco goes into SVN, I probably wouldn’t even bother checking it out in Eclipse, I would just use TortoiseSVN.


Brent Easton
Analyst/Programmer
University of Western Sydney
Email: b.easton@uws.edu.au


Messages mailing list
Messages@forums.vassalengine.org
forums.vassalengine.org/mailman/ … engine.org

Post generated using Mail2Forum (mail2forum.com)

Don’t get me wrong, I agree the documentation should be in SVN; I just thought there may be a way for the doc guys to take care of themselves; Quite a few people have shown interest in helping out but have very little IT knowledge.
But if you’re happy to teach SVN then I’m cool with that; As long as it doesn’t hinder progress on keeping the documentation up-to-date. I just can’t imagine any non-IT people I know learning SVN haha

I am somewhat of a jack-of-all-trades when it comes to computers - database management, bash scripting, OS/hardware installation - can’t do any of those things well enough to earn money, but I’m sure I can learn to use SVN (but with a Linux client, not Tortoise).

As for documentation format, I like to have a minimum of previous-next-up navigation buttons.