Add a guide book, explaining how to user rpglogger

[jefflunt]

This should NOT be part of the app. It should be a separately hosted wiki that is simply linked from the app.

wiki.rpglogger.com would be a great url, for example.

[DavidAntaramian]

I think this is a great idea. Should this be a "Wiki" in the sense that everyone can edit it, or should it be one more for dedicated admins to write for?

[jefflunt]

Dedicated admins, I would think. It could be in-app or an independent site that is hosted on a subdomain.

If it was in-app, you could also create a default LogBook for all users (when they sign up) that contains all the elements that teach them how to use the app. So when a user signs up they would have a LogBook that was called "how to use rpglogger", and the sections and world objects in it would contain on the instructions for managing data. This would make it interactive, and allow users to learn how to use the app by using it.

Thoughts?

[DavidAntaramian]

I don't like the in-app idea because it creates a lot of situational code that then has to be updated whenever the concepts in the LogBook are updated. By making it purely documentation and not interactive, you allow the system to evolve without being forced to update the documentation immediately.

I would say there are three different options for this:

A statically generated site based on a git repository

Options for this type of site include jekyll, octopress, and (nesta)[https://www.ruby-toolbox.com/projects/nesta].

Pros

• Administration can be controlled through the administration of a GitHub repository.
• Changes can be easily tracked and rolled back as well as branched and tagged

Cons

• Requires a static hosting environment which Heroku does not provide. (Nesta actually requires a Rails environment)
• Changing the live site requires a dedicated admin to first pull from the GitHub repository, compile the site, and then upload it to the host

A true Rails CMS

In this situation I would recommend something such as Locomotive, BrowserCMS, Radiant, or Refinery. I would also recommend building in custom authentication parameters to authenticate via GitHub based on the presence of an organization or write permissions to the rpglogger repository.

Pros

• Live updating of the site by any admin
• Easier to use system for a larger team of documentors
• Easily hosted on Heroku

Cons

• Would have to implement a GitHub authentication pathway
  ** All documenters would also have to have GitHub accounts too
• Requires more security updates

GitHub pages solutions

We could also use GitHub's pages solution in order to host a wiki

Pros

• Easy to implement
• Git-based, so permissions are easy

Cons

• Pages are user, project, and organization based. So without allowing someone access to the entire project, a separate organization would have to be created

On an entirely different tack, there is always (Tender)[http://tenderapp.com/plans/] which is free for open-source projects. This allows for a complete help-desk environment.

[jefflunt]

From an app management standpoint, I don't like documentation getting our of sync with production anyway, so whether it is in-app or out of app, I plan to work with others to keep it up to date at all times (or at least whenever someone points out that the support documentation is out of date).

However, I do see your point about the in-app challenges and situational code. I want to keep the codebase simple where we can, so let's keep it out of app then.

Most of the options you listed seem feasible. I'd say pick the one that is the right mix of simple/powerful, and the one that you are the most interested in running with.

Then run with it. :) Let me know what I can do to assist. Screenshots, media, image resources, writing, whatever.

[DavidAntaramian]

Could you please add a CNAME record "handbook" to your DNS listing pointing to rpglogger-guide.herokuapp.com? I think that handbook is the best way to describe this type of site.

[jefflunt]

Should be done as of a couple minutes ago. Gave you several choices. Use
any of them.

handbook.rpglogger.com
guide.rpglogger.com
wiki.rpglogger.com