r22820 : new Release Notes section under Game Settings menu

[spr]

There is a new Release Notes section under the Game Settings menu. It displays the contents of the CHANGES.txt file. Now, instead of telling users to go read the *!%%*!! CHANGES.txt file ("eh, where is that then?"), you can tell them to go read the *!%%*!! release notes section instead!

One thing that might be useful is to automatically display the release notes when a user runs a new version of Forge for the first time.

I was going to add this to a new Help & Support section but it seemed a bit pointless on its own. I do thing though that is what we should ultimately aim for. Forge is great, but can be a bit daunting for the first time user especially if (like me) they are new to MTG as well. A Getting Started page with links to helpful articles on the forum and possibly elsewhere would be a good start.

Cheers,
Steve

[Chris H.]

I like this new feature, can we add in support for displaying the README.txt file too?

[spr]

I like this new feature, can we add in support for displaying the README.txt file too?

Thanks but I am not so sure about README.txt -

• README.txt is a (relatively) big file and the home screen views are persistent. I would like to add a way of unloading this content once a new menu section is selected first. Once this is done, I would also suggest showing the LICENSE.txt file as well.
• Unlike CHANGES.txt, I am not clear what the aim of this file is - it seems to be a mixture of troubleshooting, getting started and feature highlights all rolled into one.
• I think most users will read the release notes since it succinctly details what is new or changed. I question whether many users would trawl through an unformatted view of README.txt
• A lot of the troubleshooting info assumes you cannot start Forge, so having it displayed in Forge seems a bit redundant.

These are just my thoughts and I will happily go along with the consensus.

Cheers,
Steve

[drdev]

Help documentation for an application is rarely embedded within it, which is pretty much what README.txt is. Normally there's a link to it that's easy to find in the application, but the documentation itself usually lives online.

I'd suggest we just add some quick links to important sections in the Forge wiki. I'd also suggest that anything in README.txt should also be on the wiki somewhere, ideally broken up by category, and then we add links to those sections in the application if needed.

If we're concerned about being able to access help documentation offline, we could always take snapshots of the key wiki pages and add them to the install as .html files, which can be launched in the user's default browser even without the internet. Someone could probably even write a script to automatically build those files from the wiki as part of the release process, including auto-committing them to SVN.

[spr]

I'd suggest we just add some quick links to important sections in the Forge wiki. I'd also suggest that anything in README.txt should also be on the wiki somewhere, ideally broken up by category, and then we add links to those sections in the application if needed.

I agree. I think there are some useful articles on the forum but kind of lost in the noise. Links via forge will make these much easier to find.

Cheers,
Steve.

[Chris H.]

Thank you Steve for the consideration.


When Dennis was the release dev he started the changes.txt file. Dennis retired and I took over. At some point someone decided to add in a second text file and named it README.txt.

Recently, after some discussion I decided to move several years worth of release notes from the old CHANGES.txt files in my possession to the end of the README.txt file. This material can be useful and we did not want it to disappear with the passage of time.

It would be nice if we had a good and complete instructional manual for Forge. The material that I move from the CHANGES.txt file over to the README.txt file would be best placed into this instructional manual.

Someone (Sol?) started a section in the Forge wiki entitled "Forge User Guide". At this time the content is limited but people could expand this into a useful guide.

http://www.slightlymagic.net/wiki/Forge_User_Guide

[spr]

The actual root page of the wiki is http://www.slightlymagic.net/wiki/Forge. To me this seems more accessible and welcoming than the README.txt or even the forum to a lesser extent. I think the README should only contain details on how to resolve common issues which may prevent Forge running.

But in the forum itself you also have (to name but four) -
Quest Mode: Guide to Formats, Worlds, and everything
HOW-TO: Customize your Sealed Deck games with fantasy blocks
How to Provide a Useful Bug Report
What is Forge?

I suggest creating a Help & Support section on the Home menu bar and as well as the Release Notes, add a Getting Started guide containing links such as those above. The links could be saved in a new file in the preferences folder so that they could be updated without having to change the code.

I would be happy to help restructure the wiki, but my inexperience with MTG means I would be limited in providing content. Plus I am a developer - I can't be doing with users!

Cheers,
Steve

[Chris H.]

To me, the names for our two files may be a turn off. CHANGES.txt is too tech sounding and people may not realize that we try to make this as readable as possible. Every app comes with a readme file and as such may be ignored in large part because of its name.

I sometimes wonder if it would be best to only have one file and to give it a better name. "Release Notes"? If we could append the release date to the end of this file name then it might help to get people to understand that the contents have changed and that they should go ahead and read the file.


Various devs have posted instructional messages to the Forge forum. These informative messages can get lost among all of the other messages and topics. Providing links would help but filling out the user guide wiki with the contents of these instructional messages might be the best way to handle this.

There was some discussion about the user guide wiki in the past couple of years concerning this issue. I think that we decided it might be best to have several sections.

1. Instructions for the various portions of the forge game.
2. A frequently asked questions section.
3. A technical section for modifications to the game, quest mode mods, customizing sealed deck games, etc.


Most of the current wiki was written by various devs. I believe that the user guide section is an area where some of our long term users (non-devs) could step in and help with filling out the user guide wiki.

I have made contributions to our wiki on a number of occasions in the past and I am willing to provide some assistance in this area but I can not do this by myself.