Wednesday, November 16, 2011

Wrestling with the JADE manual

Currently I feel that I hate writing the manual for JADE. Having much more fun programming JADE in one reason for that feeling. But not the only. So I have been wondering what's up and I have come to some conclusions.
For me JADE is (or will be) my masterpiece game, which is also reflected in the "JADE: The Ultimate (Edition)" name of the upcoming "thing I yet have to talk about. Considering it my personal magnus opum I feel more and more strongly that all aspects of the game and game development should be top notch.

There are some areas in which I feel I succeed:
  • Development is organized decently. We have the project management tool for JADE that I visit regularly and use primarily to decide what to change, what to fix and what to ignore (for now). (Hint: Use it ;-) ).
  • I use this blog quite regularly to discuss major design questions, updates, etc. It could be even more steady but after years of being mostly silence I am happy with the current state of communication.
  • If you are interested in the details of JADE development and want to get steady updates you can follow me on Facebook (or just register for the updates). I yet have to get better in this areas because I also would like to have a Twitter account for the updates (and don't use my regular Twitter account for that as there are many business related people following me there and I don't want to confuse them too much ;-) ). Additionally I should make more heavy use of Google+ (put me in your circles if you like). But to do that more effectively social networks either need to interact better (which probably still will take some more pressure before they do that) or I need a better tool that Tweetdeck to post messages on more than one channel (but as far as I know Google+ yet has to open its API for writing). So I guess I need to be more disciplined in this area.
  • We have the forums for discussion (and although I rarely find the time to participate I read them regularly).
  • The game itself gets frequent updates and I'm having a blast developing it.
Soon there will be news about "JADE: The Ultimate Edition" which will add something (IMHO) very exciting.

Only the manual is a work area about which I am unhappy.

So what's the reason for it?

Basically things are very simple: I hate doing ASCII manuals these days. While I love fiddling with Adobe Indesign and cool layouts for role-playing games (before the JADE revival I spent a lot of time with Hexer & HeldenGaia Gamma and The Fantasy Game and I have an extremely cool initial prototype for a Shadowrun clone with amazing images lying around... heck, I even fiddled with the ADOM RPG for a time) I just hate typing ASCII texts.

So the consequence is clear: The JADE manual needs to be more attractive than plain ASCII. But what do you think? Basically I see three options:
  1. Remain classic and do an ASCII manual. I hate every second of that ;-)
  2. Be a bit more slick and do an HTML manual.
  3. Be classy and do a stylish PDF manual with links and everything.
I have a clear preference for option #3 as it combines the best layout control with the coolest looks. And allows so much more nifty charts and explanations (at least with far less work involved) than HTML. But what do you think?

My vote is clear: #3.

Anybody concerned about that?


  1. I suggest you make a PDF. Jade is a modern game and deserves a modern manual.

  2. To be honest, I kind of hate PDFs but it wouldn't be a big deal to me either way.

    If you wrote the text in a pdf, presumably it would be pretty easy to clone it as ascii for quick in game reference too right?

  3. Do the PDF it you feel passionate about that. However I think it shouldn't be compulsory to use the manual to play. I'd see it as a way to deepen the game experience and to find help for some things you encounter in the game.

  4. I vote for HTML.
    PDF might be too heavy and hard to edit.

  5. And what about an EPUB manual? More than a simple HTML, but less heavy than a PDF. If you enjoy fiddling with InDesing, this sounldn't be a problem... although I never use Indesing for an EPUB, but it's a matter of tastes.

  6. I'd suggest a wiki-based HTML manual, with public and private versions. Public version would be online and can be updated by fans that register accounts (need anti-spam measures). Private version would be distributed with the game and it's up to you what you lift from the public wiki for that. The advantage with this is that it can be extended by fans to include hints and spoilers.

  7. Curious, for me it would be the opposite... I more or less don't mind typing text (although yes, typing documentation is quite boring). But design... oh, how I hate that! I've never been good at it and I hate anything that has to do with designing something.

    That said, for me any of ASCII, HTML or PDF would be equally fine. I wouldn't use things like ePub (or at least not exclusively) because not everyone has the software to read it. For example I don't have it and it would be quite annoying to have to download an extra piece of software to read the JADE manual.

  8. I think the HTML version would be more appropriate for a game that runs through Java Web Start =)

  9. I had an idea the other day that's kind of relevant to this. Do I remember correctly that you weren't a fan of the ADOM Guidebook because it took away the mystery from the game and spoiled the surprises?

    Well one thing I used it for was corpse effects because I just couldn't remember the damn things and some are just too catastrophic to risk. So when I read that corpses were coming I immediately thought - I hope someone starts cataloguing the effects.

    Well what if corpse effects (and other things that it would be useful for a player (not a character) to remember) were saved once experienced - a bit like the monster memory, but not erased when you die. That way there's less of a temptation to go digging through spoiler filled guides.

  10. As far as I know Google has recently opened their G+ API to the public ( You should take a look at If This Then That. It is in my opinion the best way to script and automate interaction between web services such as Twitter, Facebook, Blogger etc:

  11. A pdf manual would definitely be best. With the move to java JADE has definitely evolved from its roots, and I think a pdf manual is appropriate. Plus the fact that you actually want to make a pdf manual is a major bonus too. I don't want you to get burnout over making an ASCII manual instead of a pdf one -_-

    obscenelygreen - I'd much prefer the PC to keep an 'incharacter' list of corpse effects instead. Like potions, eating a corpse 'identifies' the effect. PCs should be able to research corpse effects in libraries/from NPCs. The success of this is determined by a combination of food preservation skill/learning.

  12. I can't stand PDFs. They were designed as a print format, and while reading them on a screen is better than it used to be, their origin is still clear, and they're still a pain in the rear for me to actually read.

    I find that the fine control over page layout that it offers is good for designers, but bad for readers. I would much much prefer to have a manual that was slightly less polished looking but gave me the option of changing page size and font size independently of each other.

    Put simply, if the manual is in PDF, I'm extremely unlikely to read it. Of course, the decision is yours, ultimately, and I won't throw tantrum if you choose the decision I don't like. You did ask for opinions, though, and that's mine.

  13. I would use ReSTructured Text (or markdown) to allow for ease of editing, and then generate html and pdfs from that with a single command (Which in the case of markdown will be basic, but ReST can generate some pretty slick documents.) But then I love editing pure text, which you state you've come to hate, so YMMV.

  14. Do it in LaTeX; render to PDF. Best of every world.

  15. I'm kinda split here.

    To be honest, I /should/ be voting for an HTML version. It's the best solution -- interoperable, lightweight, accessible, easy to change font face and size and whatnot... It's also easy to upload to the grid, for people to browse the latest version (someone suggested a Wiki, and although that's tempting, I'd rather have a downloadable guide).

    But then, the designer in me keeps thinking how cool a printed ADOM guide would look in my shelves. Of course, working on a printing press makes me even more partial to this option. :)

    (Regarding plain text ASCII -- I think that's covered well with HTML. Even if you wanted to live in a text-only environment, you have text browsers like lynx or w3. But since JADE *does* require a GUI to work anyway, the text-only dependency has lost a strong point in my oppinion.

    For the record, I used to play ADOM in console and reading the ASCII manual [and guidebook, once I had explored the game well enough], but don't feel it makes much sense with JADE.)

  16. I vote for either HTML or Markdown/reST/whatever you can compile to HTML. The manual is going to be read mostly on computer screens (in every possible shape and resolution), PDF doesn't really go well with that.

  17. Use emacs' org-mode to write in a format that exports beautifully to all 3 formats.

  18. I vote HTML, because I love the Dungeons and Dragons 3.5e open source reference guide because of how easy and fun it is to get around in it.

    What I'm talking about is this:

    A PDF manual would be a fan boy's dream but a serious reader's nightmare.

  19. PDFs are nice for stuff that's meant for print. If it's printable, it will be text on white, which is actually a pain to read on a monitor (even if many web designers haven't gotten the memo yet). You're basically staring at a lightbulb. The ADOM manual was a MUCH better read in-game, in ADOM's grey on black color scheme, than on any text processing software I opened it with. Having a manual that can be opened in-game is best from an ease of use standpoint anyway.

    So my preference would be for a manual that is accessible in game, and colored text on a black background (or at the very least not WHITE). Unless I'm quite mistaken, that is not doable with pdf. It might be with HTML.

    A sweet-looking printable pdf manual should still be included to celebrate JADE 1.0.0, when the manual doesn't need to be updated every two weeks for a release!

  20. + HTML, web based and downloadable.

  21. I'd vote for HTML. PDF is too bulky and annoying to navigate in, and how often are you going to refer to a paper based manual for a game that could update so often?

  22. As someone who has written manuals, and "read" many more, I say skip it entirely. Most users only read the manual when they're stuck with something (usually technical), and never again.

    A much more useful thing to spend your time on is an in-game tutorial, which is a more modern invention that covers the same ground a manual once did: critical keys, the interface, and sometimes character creation and overarching plot.

    If you really feel the need for documentation, a JADE wiki would be an awesome project to see started. You know that people are going to want to know the base stats of goblins, etc. and they're going to spade it out - so why not allow them to do it in a space that you control? The fact that you can also use it for news, releases, and instruction-manual-like content is just a bonus.

  23. Glossy hard copy anyone?? No?? :)

    I'd prefer an offline version in whatever format so it doesn't take an hour to access while the missus is streaming Eastenders in HD.

    I personally like obscenelygreen's thoughts about corpse effects. Is there a problem with incorporating them into the manual? It's not really spoilers...

    Similarly, the effects of potions could be described more fully in the manual (but not with the colours which should be discovered by the intrepid adventurer), e.g. Potion of Learning - Increases Character's Learning Score. The effects of some potions are not obvious even when identified.

    (he awaits the inevitable backlash of such revolutionary concepts)

  24. I agree with RonarsCorruption's sentiments. I have utilized Terraria's wiki frequently when playing the game. Wikis allow the documenter to easily and quickly provide your users with new or edited content.

  25. In addition to the manual, most of the commercial RPG games have tutorial, probably you can consider that as well. Also, I completely respect that you do not want to release the source code, however do you think you can release the API so that people can create tutorials using it and mods. (As for the mods I have not thought this through as I am not sure whether mods are even suitable for Adom, so its more of open question)

  26. I vote for a PDF! I wanna be able to print it out and put it on my coffee table so that when friends are over I can be sneaky and pique their interest in JADE without blabbing about it. PDFs can be full of cool images too and hyperlinks are nice. Leave wikis to the fans, who will inevitably make spoilers available.

  27. I've never seen a PDF manual that was as easy to navigate as a good HTML manual. I think HTML would be better, particularly as it doesn't rely on any 3rd party software other than a browser, but it's not a strong opinion.

  28. #3

    Hi Thomas - do what you like better :).

    So - go for PDF manual. It would be larger, it would need a reader, so I (being minimalist) would prefer an html manual, but after all - every kind of manual would work :).

    It's better to have a good manual than not ;) so make the kind of it that you like :). You should enjoy making it, everything made while enjoying it is made better than things made while hating them :).
    And after all, when the manual is ready it will be ported to plain text and html anyway, by other people :) have no doubt :).

    Have a nice day and do what you are enjoying to do, just like I have enjoyed playing ADom :).

    Which was one of very few games that were so interesting to play, so detailed and so _well-thought_ - that while playing it wasn't irritated on anything ever :). Sometimes only wished, there would be this or more of that... so thinking of JADE now :)

  29. I prefer HTML or any other format that makes it easy to change font sizes and reflow the text.

    PDF is a pain in the ass to read when you have bad eyesight.

  30. I vote for PDF to be packed with a game distributive. If you make one - you'll have all the text there is to release HTML for online manuals, formatting in HTML is a piece of cake. People can save it if they want, duh.

  31. A) Make a PDF with links, convert to HTML, distribute both.
    B) Make a HTML version, convert to PDF, add graphics and such to taste, distribute both.

    I don't see why you can't have your cake and eat it, too. So just pick whichever one you will work on, will finish, and will be proud of.

    Except ASCII. Don't pick ASCII. I don't think anyone wants that.

  32. The PDF sounds shiny. An HTML reference would also be pretty awesome, but that could just as easily be a community work.

    It's true that a PDF is inconvenient for looking stuff up. But there's not much you'll need to look up in it after learning about the interface. Aside from stuff like class powers and bonuses, most of what you'll want to know is better answered by a strategy guide, and the community is good at writing those.