PDA

View Full Version : Manual updates



Moon Wizard
July 17th, 2012, 20:55
OK, so I've been swinging back and forth on different manual platforms over the last year, with no clear winner. So, I decided to go with the easiest option for us to manage (Google Sites), and make the best of it.

The current manuals are written using XML/XSL, so they are not conducive to sharing. Also, the current layout prevents programs from Adobe Acrobat from creating PDF files.

Here is a preview of the new layout for the manual sites.
https://sites.google.com/a/smiteworks.com/user-guide-basics/

My idea is that by placing it on a collaborative site, I can invite interested community members to update the existing sites with more information. Also, I can allow other ruleset creators (via FG or community) to create their manuals online, and I can easily link to the main web site.

Right now, I've only migrated the launcher portion of the manual as a test of the layout and formatting.

What do you think so far? Any issues you can think of?

Regards,
JPG

wbcreighton
July 17th, 2012, 22:09
First issue:

I get this error:

The ‘Insufficient Privileges’ error message in Google Sites often means there’s an item embedded on the page that you don’t have permission to view.

Zeus
July 17th, 2012, 22:39
I had the same issue however my access is now working. Try again wbcreighton.

wbcreighton
July 17th, 2012, 23:28
Thanks :) :)

Zeus
July 18th, 2012, 07:27
I like it moon. Nice and clean.

Once comment: the screenshots, which are intended as a visual reference, are a little too small for me, causing the text to be illegible. I know you can click the image for a full size version however you then lose visibility of the manual text. This causes lots of clicking between manual pages and inserted screenshots.

Instead of a side by side format of screenshots with manual text, it maybe better to go with a top down approach; this should allow for a slightly larger view of the screenshots and will hopefully negate the need to enlarge the image.

This should also ease any conversion to PDF and the flow of the document elements.

Moon Wizard
July 18th, 2012, 08:45
I found that the larger screenshots actually took up a fair amount of real estate on the screen as well, so you would end up scrolling between image and step-by-step.

The main questions are whether legible text is a requirement for the images on the top page, and whether drill-down vs. scrolling is preferred.

Regards,
JPG

Callum
July 18th, 2012, 14:55
I think this is a great idea, and I look forward to being able to contribute!

To my mind, the screenshots definitely need to be larger. Even on my laptop (at 1280 x 800), there was plenty of room for larger images, and the current ones are just too small to be seen clearly. I'd increase the size of the screenshots next to the text by 50% in each direction, and those that you get when you click on them by 100%.

The current navigation system seems to work fine.

In Firefox, the numbers in the lists of instructions aren't centred in the text boxes - they're all sitting low, hanging over the bottom edge of the box (this doesn't happen in Chrome or IE9). These numbers are also rather large, meaning even a single line of text takes up a lot of space - could they be reduced in size a bit?

Dakadin
July 18th, 2012, 15:22
You might not need to change the size of the screenshots if you added the numbers to the screenshots. For example, step #1 for Load Campaign says Click "Load Campaign". If there was a small #1 with a similar style on Load Campaign button that might work instead.

Moon Wizard
July 19th, 2012, 20:21
The big images for the screenshots are 50% of the original screenshots to save space. These are the images used in the current manual. I'm open to using full size images. I just need to check to see if there are any space limitations.

The small images for the screenshots are actually controlled by a built-in widget, and that size is the largest size available without going full size. I'm not in love with the widget though. I might be able to bring in a light box similar to current manual with some work.

My main concern is making sure that it is easy to build, which means that I don't want to have anyone have to maintain multiple sizes of same file. Any HTML gurus have suggestions?

Cheers,
JPG

Moon Wizard
July 19th, 2012, 20:58
I just redid the graphic on this page. What do you think?
https://sites.google.com/a/smiteworks.com/user-guide-launcher/load-campaign

* I used a full scale graphic, and had it resize to fit box with a link to full version. My only concern is that the full graphic has to load for each page that has a screenshot, but they are about 180K as JPGs, so not bad.
* Also, I shrunk the step by step graphics by 25%.

Cheers,
JPG

Trenloe
July 19th, 2012, 21:06
I just redid the graphic on this page. What do you think?
https://sites.google.com/a/smiteworks.com/user-guide-launcher/load-campaign

I used a full scale graphic, and had it resize to fit box with a link to full version.

Cheers,
JPG
I think that approach - works well for the initial layout and gives more details if needed.

Dakadin
July 19th, 2012, 21:37
I just redid the graphic on this page. What do you think?
https://sites.google.com/a/smiteworks.com/user-guide-launcher/load-campaign

* I used a full scale graphic, and had it resize to fit box with a link to full version. My only concern is that the full graphic has to load for each page that has a screenshot, but they are about 180K as JPGs, so not bad.
* Also, I shrunk the step by step graphics by 25%.

Cheers,
JPG

It looks good. The graphic is easy to see when following the instructions.

Zeus
July 19th, 2012, 22:54
Yeah thats much clearer to me now.

Moon Wizard
July 19th, 2012, 23:38
Cool, let me redo the rest of the launcher pages, and start on the 3.5E and 4E manuals. Once I have the current manuals migrated, I can create copies for other rulesets and/or add contributors to the 3.5E/4E manuals.

Cheers,
JPG

Callum
July 20th, 2012, 12:56
I just redid the graphic on this page. What do you think?
https://sites.google.com/a/smiteworks.com/user-guide-launcher/load-campaign

* I used a full scale graphic, and had it resize to fit box with a link to full version. My only concern is that the full graphic has to load for each page that has a screenshot, but they are about 180K as JPGs, so not bad.
* Also, I shrunk the step by step graphics by 25%.
Yes, that's excellent - so the image scales depending on how much screen area you have available, and you can click through for the full resolution version. I don't think anyone should have a problem with 180K images - and if they do, they'll probably have trouble running FG!

The smaller step-by-step graphics are better, too. In Firefox, I'm still getting those graphics sitting low, though - which also makes the outline boxes bigger.

Moon Wizard
July 20th, 2012, 23:35
Just moved the site to:
https://sites.google.com/a/smiteworks.com/user-guide-basics/

I wanted to try and move the "basics" type of material into it's own manual, so that every manual writer didn't need to copy whole sections.

Also, I tried playing around with the Google gadgets to see if I could create some tools to allow quicker publishing of common items (i.e. step by step tables, etc.). From the morning I spent playing with the gadget API, the gadgets appear to be only lightly supported at this point. (Some things don't work on Sites vs. iGoogle, iGoogle is going away, etc.) For now, it's going to be copy and paste HTML to keep things moving. If someone figures out some good gadgets to use, let me know.

I'm trying to add a few pages and/or screenshots a day to keep things moving.

Cheers,
JPG

Zeus
July 21st, 2012, 08:43
moon.

Q: Do you plan to also move the Developer Ruleset Modifications and Ruleset Reference Manuals over to the new site as well, moving forward.

If so for the reference manual, could you incorporate space in the template to host code examples for each method/group of associated methods. I'd be willing to assist is helping populate the example code references.

Moon Wizard
July 23rd, 2012, 19:11
I haven't decided on those sites yet, though the reason you gave is a good one. (i.e. comment and example code capability)

The user manuals have been the most problematic, so they are the first up for change.

JPG

SLB
July 25th, 2012, 06:16
I think this is a great idea - allowing for contributions from the community will be very helpful. Often the current manual tells me exactly what to do but I need a couple more examples to understand the concept in practice (specifically around the new functionality which came with the 2.8 upgrade).

I especially like the fact that it will make it possible for a PDF version of the manual because I'm old and I like paper :P

Which, I suppose, makes it ironic that I play a "Pen & Paper" game electronically?

Moon Wizard
July 26th, 2012, 20:16
Been busy this week with main job, but I have been focusing on adding content to the new manual.

I've decided to try a new approach where I embed all the common elements in a FG Basics manual, even if the elements are not in all rulesets. I just add a note that not all rulesets contain that capability, and move on.

Then, for those sections that need ruleset specific sections, link to a ruleset specific manual sections stored in a separate site.

Right now, I think I have all the sections built for non-ruleset specific material, with placeholders for the sections that need more detail relevant to specific rulesets (i.e. asterisks next to topic name).

This will allow me to maintain the core manual, while allowing me to spin off manuals to be managed by the community for the ruleset specific sections.

What do you think?

Regards,
JPG

Bidmaron
October 23rd, 2012, 01:46
I found that the larger screenshots actually took up a fair amount of real estate on the screen as well, so you would end up scrolling between image and step-by-step.

The main questions are whether legible text is a requirement for the images on the top page, and whether drill-down vs. scrolling is preferred.

Regards,
JPG
JPG, why not have both? That is, you can have it where you can drill down to lower in the page and those who want to scroll can simply bypass the 'drill down'? The reason I like the scroller is that you can save the web page and have an off-line version of it, which is a lot harder to do for a drill-down.