Here’s a second draft of the 3.1 user guide. This incorporates all the comments so far and adds some new sections. Thanks for the feedback.
Very Good job !!!
May i suggest you to include few pictures to give more visual information …
I join you here the generic part that i have used in, my own documentation 3.0 …
I can provide you help for screen capture if you want …
Regards,
Grégory
Thus spake “mycenae”:
Comments:
p.1
-
The banner should be embedded in the PDF as a PDF, in order to preserve
crispness. (I assume that what’s embedded here is a bitmap?) Anyway, the
source you’re working from needs to be adjusted so as not to be blurry.
I’m taking care of this. -
VASSAL case: This is something we need to settle. On our current site,
it’s “VASSAL”, all caps. All caps tends to look too heavy, so on the new
site I’ve put VASSAL in small caps. (This is a commmon solution. E.g.,
in well-typeset books, you’ll see acronyms like “NATO” in small caps.)
In the site banner, I lowercased everything because I could find no other
way to make it look decent. I don’t like “Vassal”, which is what’s in the
guide now.
p.3
- I’m not a fan of spelling out the whole URL for the download link, it’s
too verbose. I think this is better:
You can freely download VASSAL 3.1 from the VASSAL site.
This way, the link points to the location, but the link text is meaningful.
-
The “x” in 3.1.x is the micro version number, not the minor version number.
“1” is the minor version number. -
.zip is not what you’d expect for an archive on Linux, so starting with
3.1.3 I’m going to build .tar.bz2 archives for Linux, not ZIPs. -
Windows ME also works with Java 1.5 (but not 1.6), but isn’t in the list.
-
It’s probably worth noting that it’s possible to run VASSAL (using the
“other” bundle) on any other OS which has a suitable version of Java.
p.4
- For 3.1.3 and later, installation on Linux will be ‘Untar
VASSAL-3.1.x-linux.tar.bz2.’ From the command line:
tar xjvf VASSAL-3.1.x-linux.tar.bz2
p.5
- Throughout, “zip file” should be “ZIP file”. ZIP is the name of the
file format, .zip is the extension which ZIP files tend to have.
p.6
- The names of some context menu items in the docs don’t match what is in
the context menu right now. “Synch” in the docs is “Synchronize” in the
menu. “Send Private Msg” is actually “Private Msg” in the context menu, but
probably should be changed, since it’s bad to have no verb in the context
menu item name.
p.7
- “Send Wake-Up” is actually “Send Wake-up” in the context menu.
p.8
-
Several of the numbers in the numbered lists are bold, but should not be.
-
“Synch” again.
p.9
- We have em-dashes for numeric ranges now, instead of the hyphens we had
before. They should be en-dashes.
p.11
- “Note that only the map graphic rescales–the window size…” This
should be an em-dash not, two hyphens.
p.13
- “Usually, decks are randomly shuffled by Vassal after each draw,”
Is this true? If it is, then we’ve done something horribly wrong in the
way we’ve implemented decks. E.g., this would make it impossible to play
games where the order of cards in a draw pile matters.
- “Extensions do not need to be installed…”
I would say instead that the process you call activation is just how you
install an extension. (De)activation is what you can do within the MM after
you’ve installed an extension.
p.15
-
“Specifies in which to display the module” Missing “language”.
-
“Prefer…” Missing period at end of description.
-
“High-quality…” Ditto.
p.16
-
Updating VASSAL: VASSAL also checks for updates on startup if the last
check was more than 10 days ago. -
Helpful Apps, second bullet point: “but other solutions that may” should
be “but other solutions may”. -
ConsimWorld writes their name as “ConsimWorld”, not “ConSimWorld”.
-
“Synch”
–
J.
Messages mailing list
Messages@forums.vassalengine.org
forums.vassalengine.org/mailman/ … engine.org
Post generated using Mail2Forum (mail2forum.com)
No it’s not’s - this is an option set by the designer. It would be better to omit or clarify this as it is misleading
my comments not caught by others so far (don’t make changes according to this unless Joel/Brent/Rodney sign off/agree with these):
P.4 - Play options:
“It is important to remember that vassal does not enforce any game rules…” - misleading, it can with a lot of complexity or custom classes added. Should clarify to something like:
" In general, Vassal does not enforce game rules (for exceptions see designer handbook etc…)…"
second paragraph - clarify for same as above
P.5 Launching Vassal:
step 4 - no mention of the other options - shouldn’t they be described in brief what the differences are?
“step 8. Click Finish
Your game now loads and you are…”
Not quite- if Im following step 4 as written (Look for a Game Online), the module loads, no game actually loads, this is done with one of the other play mode options (Load a saved game) or after connecting and starting a game
P.7 Server Management
Public message - this is really more of a public email system. Players circumvent it by just typing in the public chat. I doubt they are constantly refreshing the msg board while all are on to talk to each other. Might be better to describe it as a email type system
P.7-9,12
Player passwords are briefly skimmed in playing by email - it applies to all modes and probably deserves a section all unto itself stressing it’s importance as how player profiles/passwords/sides work as this is a common problem we get posted on forums
P. 12 Stacking 3rd paragraph
Pieces do not have to be identical to perform the same command on all. The only requirement is that the selected pieces share the same command (and key) then they will perform that action
P. 14-15
Java Heap - need to denote how to set size, cannot be more than 1300mb (I think) for Windows32. Exceeding actual physical ram is detrimental and pointless - A Developer should elaborate for this in better depth