Create account / Log in

Online Reference Manual

Topics related to the main Vassal engine.

Moderators: uckelman, Tim M

Online Reference Manual

Postby Brent Easton » January 11th, 2008, 5:14 am

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

Brent.
User avatar
Brent Easton
 
Posts: 2983
Joined: December 21st, 2007, 3:06 am
Location: Berry, NSW, Australia

Online Reference Manual

Postby rk » January 12th, 2008, 12:52 am

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

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 (http://www.mail2forum.com)
rk
Site Admin
 
Posts: 536
Joined: October 21st, 2007, 3:31 am

Online Reference Manual

Postby uckelman » January 14th, 2008, 9:47 am

Thus spake "Rodney Kinney":
Is there a copy of the VASSAL reference manual online on the vassalengine
site that we can link to from the wiki?


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

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
http://forums.vassalengine.org/mailman/ ... engine.org

Post generated using Mail2Forum (http://www.mail2forum.com)
User avatar
uckelman
Site Admin
 
Posts: 8571
Joined: December 10th, 2007, 9:48 am
Location: Durham, England

Postby bsmith » January 14th, 2008, 10:02 am

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.
User avatar
bsmith
Site Admin
 
Posts: 657
Joined: October 2nd, 2007, 4:47 pm

Online Reference Manual

Postby uckelman » January 14th, 2008, 10:34 am

Thus spake "bsmith":
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 lik
e 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 effe
ctive documentation at this point in time.


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
http://forums.vassalengine.org/mailman/ ... engine.org

Post generated using Mail2Forum (http://www.mail2forum.com)
User avatar
uckelman
Site Admin
 
Posts: 8571
Joined: December 10th, 2007, 9:48 am
Location: Durham, England

Postby meng » January 14th, 2008, 6:51 pm

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.
meng
 
Posts: 124
Joined: January 14th, 2008, 6:35 pm
Location: Melbourne, Australia

Postby bsmith » January 15th, 2008, 6:06 am

meng wrote: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.

:lol:
User avatar
bsmith
Site Admin
 
Posts: 657
Joined: October 2nd, 2007, 4:47 pm

Postby bsmith » January 15th, 2008, 6:20 am

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?
User avatar
bsmith
Site Admin
 
Posts: 657
Joined: October 2nd, 2007, 4:47 pm

Online Reference Manual

Postby Brent Easton » January 15th, 2008, 7:34 am

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:

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]







_______________________________________________
Messages mailing list
Messages@forums.vassalengine.org
http://forums.vassalengine.org/mailman/ ... engine.org


--
No virus found in this incoming message.
Checked by AVG Free Edition.
Version: 7.5.516 / Virus Database: 269.19.2/1224 - Release Date: 14/01/2008 5:39 PM


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


_______________________________________________
Messages mailing list
Messages@forums.vassalengine.org
http://forums.vassalengine.org/mailman/ ... engine.org

Post generated using Mail2Forum (http://www.mail2forum.com)
User avatar
Brent Easton
 
Posts: 2983
Joined: December 21st, 2007, 3:06 am
Location: Berry, NSW, Australia

Online Reference Manual

Postby uckelman » January 15th, 2008, 9:27 am

Thus spake "bsmith":
This documentation should be hosted on vassalengine.org in html format. I th
ink we should avoid including any docs with the distribution, this seems to b
e 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 simp
le.

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
http://forums.vassalengine.org/mailman/ ... engine.org

Post generated using Mail2Forum (http://www.mail2forum.com)
User avatar
uckelman
Site Admin
 
Posts: 8571
Joined: December 10th, 2007, 9:48 am
Location: Durham, England

Online Reference Manual

Postby uckelman » January 15th, 2008, 9:32 am

Thus spake "bsmith":
This is sort of layout we should be aiming for in the long-term; Two frames w
ith a hierarchial index.

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

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
http://forums.vassalengine.org/mailman/ ... engine.org

Post generated using Mail2Forum (http://www.mail2forum.com)
User avatar
uckelman
Site Admin
 
Posts: 8571
Joined: December 10th, 2007, 9:48 am
Location: Durham, England

Re: Online Reference Manual

Postby bsmith » January 15th, 2008, 10:25 am

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.
User avatar
bsmith
Site Admin
 
Posts: 657
Joined: October 2nd, 2007, 4:47 pm

Re: Online Reference Manual

Postby bsmith » January 15th, 2008, 10:28 am

uckelman wrote: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.


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.
User avatar
bsmith
Site Admin
 
Posts: 657
Joined: October 2nd, 2007, 4:47 pm

Online Reference Manual

Postby timpelican » January 15th, 2008, 10:50 am

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

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.

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
http://forums.vassalengine.org/mailman/ ... engine.org

Post generated using Mail2Forum (http://www.mail2forum.com)
timpelican
 
Posts: 171
Joined: January 2nd, 2008, 3:50 pm

Postby bsmith » January 15th, 2008, 10:53 am

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.
User avatar
bsmith
Site Admin
 
Posts: 657
Joined: October 2nd, 2007, 4:47 pm

Next

Return to General Discussion

Who is online

Users browsing this forum: No registered users and 2 guests