Vassal documents

Hi all,

I’ve volunteered to organize the Vassal documentation. Joel and I have been speaking about it and he’s been very helpful answering all of my questions. I’ve begun roughing out a documentation plan for 3.1.

RL I’ve been a technical writer for the last 10 years, and I’ve created something like 20-30 Vassal modules plus extensions, so I have a fair amount of relevant experience. Improved documentation is important to the success of Vassal and I’m eager to work on it. The beginning of the process is collecting the existing docs and outlining the deliverable documents.

I’d love to hear your thoughts on what you think of the Vassal documentation right now, and where you think it needs to go.

Awesome! It’s great to have somebody own the documentation.

For organizing the documentation, I’d think in terms of a couple of user persona:

Curious Investigator: This is a user who’s just heard of VASSAL on a form somewhere and is downloading it to see what it can do. There should be a one-pager on the web site for him. Within the program, the tour is mostly focused on this user. After walking through the tour, he mostly needs instructions on how to load a module and a pointer to the web site where he can browse for modules.

Focused Player: This is a player who wants to play, say, star wars minis or w40k. All he knows is that he needs this VASSAL thing to do it. Most of VASSAL’s functionality just gets in his way, so he wants to know how to get his module loaded, connect to the server, and start up a game in as few steps as possible.

Module Designer (Beginner): Somebody who wants to make a module for a game he has in mind. Needs to be walked through the basics of how maps, boards, counters, cards, and player sides are represented and how they interact. He needs a straightforward tutorial to get oriented, decide if wants to get serious and graduate to …

Module Designer (Advanced): Here we need a big fan-out of examples of all the esoteric things you can do in the system. We can point to modules in the archive and somehow organize them by the techniques they achieve. Some categories off the top of my head: limited information, dealing cards, interactions between pieces. Then just a one-liner for each example module, such as “deal cards from a deck equally to all players” Once users are at this level, they don’t need much verbiage, just lots of examples.

Module Programmer: For people who want to write Java code, we need an introduction to the key classes in the code base, and instructions on how to get the source and set up a development environment.

So where do we stand? For the Curious Investigator, we have an overview on the web site, and the tour. And there’s the Getting Started guide, which is now in the wiki. These are the essential elements, but they need to be integrated. For the Focused Player, we don’t have anything specifically targeting him. Really dedicated modules end up writing their own installation and Quick Start guides. For the Beginning Module Designer, there are the module-creation tutorials on the wiki. These are reeeeally old, although the information is still accurate for the most part. We should update the first tutorial and let the others wither. They’ll be replaced by pointers to real modules that do the same things. (At the time I wrote those tutorials, there actually were no such examples of real-life modules.) The programming tutorials on the wiki are also old, but also still mostly accurate.

My sense overall is that people go fairly quickly from curious to advanced, if they don’t get turned off by the initial experience. I think we should focus on making sure we have a very friendly initial impression so that we don’t confuse people who are just checking VASSAL out, and then focus on building up a library of examples that’s comprehensive and easy to maintain.

rk

Post generated using Mail2Forum (mail2forum.com)

I’m posting here my reply to Ed’s question which I’d previously sent him
by email. My view of what we should have for documentation is a bit different
from Rodney’s:

The last time we developers talked about it, we identified these kinds of
documentation: for users, for module designers, for developers. For users
and module designers, there’s a need for both introductory and reference
documentation. Reference documentation is not useful for beginners, and
introductory documentation is not useful for experienced users who want
to look something up. There’s a need for all four of these—user tutorials,
a user reference manual, module design tutorials, and a module design
reference manual. There is much less urgent need, in my opinion, for
better developer documentation, if for no other reason than it serves so
few people.

In terms of priority, I would order them this way, in descending order:

user tutorials
design tutorials
design reference manual
user reference manual
developer documentation

So, our point of agreement seems to be that a Tutorial for beginning users
is the thing most urgently needed. I hadn’t mentioned Module Programmer docs,
but I think something detailing the internal architecture of VASSAL would be
as useful for new developers as it would be for module programmers. Rodney
doesn’t mention any reference documentation; I think it would be a serious
mistake not to have reference documentation for module designers. Reference
documentation for users can be pretty short, as there’s not that much stuff
to explain (the bulk of it would be preferences settings, I think).

We definitely need reference docs for module designers. The Reference Manual that comes with VASSAL is actually the only piece of documentation that we have that’s both comprehensive and up to date, so I figure we keep that one around, translated into whatever common format we decide on.

rk

Post generated using Mail2Forum (mail2forum.com)

My thinking is that tutorials need to supplement guides. We need both, but it’s a question of completeness. My sense is, right now, we don’t have a comprehensive documentation set, and I think we need that before we start producing tutorials or putting it into other formats. I believe it’s best if we collect and cover the information first in guides–user, reference and developer–so we get all the information collected, updated and published.

(What I’m referring to as a ‘guide’ could be a single book-type PDF manual, or could be a set of HTML pages. The actual format is immaterial–the idea is that it’s a unified reference with all the important features and procedures.)

Then, we highlight the topics that are most troublesome, or could use further detail, based on what people ask about most frequently, and make or update tutorials based on that. For example, it seems to be a common question on the forums for a player to connect, but not see the other player’s pieces moving around. So, clearly we need a tutorial on connecting to a game and synching up. But I’d link to it as ‘further reading’, or ‘try it out’ from the relevant section of the user guide.

If we do these topics as tutorials first, then cobble these together later into a guide, we risk missing valuable information. The coverage may not be as complete, because by their nature, tutorials don’t include everything. Also, a unified guide is easier to maintain and update.

This method of going from the general to the specific can extend to publishing docs in other formats besides tutorials. For example, we could draw from the guides to create a one-pager for what Rodney calls the Focussed Player. We need all the information in one place first; then we can decide what to highlight to put into the one-pager for a 40K player who only needs to know the barest minimum about this Vassal thing.

The way I see the user guide as written, it would give stepwise procedures for performing tasks, and probably include screen shots from suitable example modules, like the Tour module. For example, broadly:

To connect to a game:

  1. Launch Vassal.
  2. From the modules list, select a module to play.
  3. Click the Connect (screen shot of two arrows) icon.
  4. In the Connection window, double-click on the room you want to enter.
  5. Right-click on a player who’s already launched the game, and choose Synch.
    etc.

I’ve started drafting a guide along these lines for 3.1, but I’ve been using 3.0 and need to get caught up on the new features.

The designer’s guide can’t do as much of this type of procedure, obviously, because the overall procedures for designing a particular game aren’t as clear-cut. So it would become largely a catalog of features, bundled with best practices when designing a module to pull it all together.

Thoughts?

That’s excellent, thanks.

I administer the forum, submit code snippets and contribute to discussion on where the project should head.

By the way, what’s your real name? Or should we call you “mycenae”? :smiley:

Ben

That makes sense to me. I do feel that the first documentation that the user sees should be short and easy to digest. So rather than first handing them the comprehensive guide first and directing them to additional reading for walk-throughs on how to connect to the server (for example), I’d want to first present them with the short walk-throughs and then direct them to the comprehensive guide for more details.

rk

Post generated using Mail2Forum (mail2forum.com)

That sounds reasonable. I’m working through a draft of a user guide atm. I’m trying to make it concise; I don’t think it would be much longer than 10-12 pages if we put it in, for example, PDF format.

I’ve an eye towards boiling it down to the front/back of a single sheet of paper at some point; maybe the “Quick Reference” guide could be included in the Help menu in a basic Vassal installation. Something, as you say, short and easy to digest.

I expect to finish the draft by the middle of next week. I’d like you all to review it before we post it, of course…so what’s the best way, and the best format, to get it to you, and to collect feedback?

-Ed

Thus spake “mycenae”:

What’s the source format you’re working in?

It should be possible to upload a PDF here.


J.


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

Post generated using Mail2Forum (mail2forum.com)

Right now, the source doc is in the much-hated MS Word format, for convenience. But I can easily change to another format (such as PDF or non-MS HTML) if that would be easier…

-Ed

Thus spake “mycenae”:

In the long run, I would be much, much happier if the source were in an
open format.

For the purposes of having a look at the output right now, MS Word is a
poor format for people who are not using Windows (and even for people who
have an older version of Word, I hear). Either PDF or HTML would be fine
for everyone, I expect.


J.


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

Post generated using Mail2Forum (mail2forum.com)

HTML would be preferable by far, as it is the most flexible.

  • M.

2009/3/5 Joel Uckelman <uckelman@nomic.net (uckelman@nomic.net)>

Post generated using Mail2Forum (mail2forum.com)

None of which is really suitable for easy co-operative development. Unless you want to be writing the whole shebang yourself, you will need to rope in developers and other volunteers to write different bits and pieces of the doco.

At one stage we discussed developing the documentation in MediaWiki which has plug-in modules to export a section of the wiki as static HTML or PDF.

PDF and HTML are fine as target doco for viewing on website or downloaded with Vassal, but not as source.

B.


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

Post generated using Mail2Forum (mail2forum.com)

To clarify: Only the User guide is currently in Word format. It’s reasonably brief and I am writing it myself. After we get the content finalized, I will distill it into a 1-page handout that summarizes the major points.

There is also a short section in the user guide for FAQs, that begs to be expanded, most likely into its own document.

For the designer and developer’s guides, since I’ll be soliciting content from people, it makes sense to keep the content for these guides as a wiki so that anyone can contribute. However, let’s be careful here: we need to validate what people contribute to a wiki, and ensure accuracy and currency.

The core and major portion of the designers’ guide will be the 3.1 online help. However, the online help describes all features, but doesn’t give a larger context for how it all fits together. It gives the vocabulary, but it doesn’t explain to how form sentences.

For this guide, I’ll also be seeking content on getting started for designers, as well as a best practices section that shares tips and tricks from experienced designers. There should also probably be a section on performing common tasks: how to use traits, how to use properties, creating a card deck, etc.

Once we get the content squared away on both these guides, we can extract tutorials that illustrate common tasks, and revise the existing tutorials in light of current content.

The developers’ guide is a more nebulous target, and farther down the road, since I have little insight into what currently exists, what is needed, and how big the audience will be. As a result, this content is a much lower priority than the other stuff.

I’d prefer that the any wiki content be exported at intervals (for example, after a major release) to PDF so we can get actual book-type guides. But that’s my own preference: I think it’d be nice to be able to give a designer a unified, indexed reference on how to create a module, rather than pointing them to a set of wiki pages that they need to hunt around in.

Thoughts?

-Ed