ORIGINAL: Red Lancer
As the OP was on another forum, can we here, please treat his comments with the same graciousness as Joel. As the OP may not be a Matrix forum member with an ability to reply we ought to avoid group think. Although don't think that I take umbrage with any posts so far. I love discussion and argument but detest imbalance and rudeness.
Better still can I encourage you to use this thread to provide any thoughts you may have to make the WitE2 Manual a joy to behold. The author is a forum regular (not me!) and I know he will be reading.
So confession time .. I'm doing the manual. And yes am reading avidly any commentary on the existing documentation for both WiTE1 and WiTW - and have found the type of issues raised by those brought to WiTW via Steam very informative as these are less likely to have graduated from paper maps and counter style games.
I've a mixed background - I sometimes lecture in Social Policy research methods, I make a fair bit of my income doing social policy evaluation, I edit documents for the rest of my living and have written on line pedagogic (ie teaching) material focussed on how to conduct research projects. Across that, have a very simple view, if the reader/user mis-understands something its not their fault, its a flaw in the explanation.
So what are we trying to do?
a) we are retaining Red Lancer's brilliant one page guides from the WiTW documentation. I still use these when playing that game as they really capture the key issues;
b) we are trying to write up the manual so there is a single early chapter that covers the key game concepts and how to play the game. Its deliberately detail light and written in the second person (you do ...) and includes a detailed walk through of the intro scenario (incl not just what but why comments);
c) the rest will be detailed but issues such as define terms, abbreviations in a single easy to find place have been adopted; and,
d) If the underlying system matters because its something the player can directly affect using the tools provided - well it will be described in detail (but hopefully in a comprehensible way), if the underlying system is critical to the game well again there will be detail (even if the actual operation is almost all in the game code) , if its something that goes on in the logistics phase out of sight then the description will be indicative. None of these categories are hard and fast ... and of course there is no single approach that will satisfy everyone.
The end product hopefully will be documentation that allows a new player with or without experience of WiTE1/WiTW to get into the game and say win a Road to ... scenario vs the AI on neutral settings. But there is also a need to produce a comprehensive reference manual that goes much beyond this.
At this stage the documentation is tentative. We are close to a decent first draft of the manual but major issues of layout/format etc have not even been thought about. Never mind supporting material such as videos etc.
I'm trying to find and follow almost every documentation related thread I can find (the Wargamer has a good critique of the WiTW manual as an eg). As Red Lancer says, raise issues here, they will be read, they may help improve the material supporting WiTE2.
Edit:  - the movement rules are an example of this. In practice, in both WiTE1 and WiTW, you left click on the unit(s), the map changes to show you how far you could move, you hover over a hex and a movement path with the cost in MP is overlaid, you right click to execute the move. So unlike a paper/counter game you don't need to add up MPs as you move (ie where you would need a detailed movement cost table) as its done for you. However, I'd very strongly suspect that all of you would be surprised if there was no movement cost chart in the manual? Not least you might want to work our why you can't move to where you want to reach, or be planning moves in advance and want some idea of the likely costs.
I'm very happy to hear that you are doing the manual - I read many of your forum posts (and often searched specifically for your posts if I needed some information and have stored many in my Evernote database) and always thought that they were extremely informative and really geared toward helping others to understand what's going on or how to resolve the issue they had.
I think the list above makes a lot of sense. Some additional points:
- I think a lot of new players often struggle less with the "how" but the "why & what" when playing new games. So in good AARs / Let's play the author first states the goals and then derives the actions from that instead of just making some moves and leaving the newbiw behind with the question of "why?"
- What I find often very helpful (especially in boardgames but also computer games) are "designer notes" where the designers explain certain concepts and how and why they were implemented. I think this is especially useful the more abstract games get to help the player connect the games concepts with the "real life"
- I really like how certain manuals use inserts of examples throughout the text to immediately explain the concepts. The Holland '44 manual I linked above is a good example, another one would be the manual of "Enemy Action: Ardennes" from Compass Games.
Let us know how we can help so that you can best help us by writing the best possible manual