Configuring Makahiki: Thorough Walkthrough.

Taking steps into the Makahiki System, I've taken a go at going through a configuration and management log page providing some step by step experimentation with creating some of the basic set up and activities for Makahiki based on the Kukui Cup template. Each point on this page leads to a portion of the documentation for the Makahiki system related to it. In approaching this tutorial I wanted to take the mindset of both a mindful programmer, and that of a new user consulting the instructions casually, that way I could assess the structure of the system and the instructions as best as I could.

Throughout my exploration of the system, there were not any significantly detracting points to it. But there were some things that lacked clarity. Going into each of the tutorial's links to the relevant section of the guide felt partially disorienting, because they are established as individual pages, they feel disconnected from each other, this is good since each section is long, but at the same time the disconnect creates an issue when referring to specific areas to click or access. For example in 2.3.6.8.2  one is told to, 'click on the "Badges" link in the Game Admin Widget,' it becomes necessary if linked directly to that part by an instruction, to go back to 2.3 and look over that area to remember the widget in question. For a tutorial this problem isn't significant at all (since one is going from point to point) but if referenced out of context, like for example if someone is asked to make a badge, they might go straight to that bad and not realize or remember what and where the widget is. This is apparently through most of the guide going forward, and is not a major flaw but one that requires more navigation for a reader. Mentioning that the widget is located in the settings page might help to alleviate that kind of disconnection.

Early on in the tutorial, there was a small portion that I personally stumbled over where the user is asked to disable the water games from appearing. The instinctual answer to that would be clicking on the "Water Game Settings" to do so, as they are settings for the game. In addition, the actual location (the wording above, noting the category of "Water Game" itself is small, and in some situations not a link at all, created a moment of rereading the documentation in order to find the right location.

The documentation does not mention in the area about the events and excursions (2.3.6.3.2.3), how exactly to generate the codes for participants and even if that is clarified in other sections of the guide there is no reference to where that is. Thought it is found in the set up for the event, under "View Confirmation Codes" it is not clearly stated that this is where code is also generated, and I only made the assumption this is the place to go to after not finding any sign of confirmation code generation on the creation page.

Based on the tutorials for activities, (Which used section 2.3.6.3.2) the documentation mentions creative actions as a type of action to create, though it is an activity, which could be confusing to a developing administrator. This could either be alleviated as making it part of the Activity portion of the tutorial or by creating another type of action. Which action would be taken would probably depend on whether the developer would want creative actions to be separated as to not feel like an obligatory activity compared to more straightforward activity tasks, or if they want to maintain that the two types (activity and creative) are done in a similar manner compared to events and commitments.

In general these is an issue with the documentation of Predicates for the Makahiki system (4.5). No explanation for the parameters is given, and the formatting provided by the documentation is not used in the system itself. For example:

 apps.widgets.smartgrid.predicates.completed_some_of_level(user, some=1, level_name=None)

is given as a Predicate, but within the system only

completed_some_of_level(2, "Level 2")

 where 2 is the level and "Level 2" is the name of the level is used. If that were not provided as an example in screenshots, using predicates would be more difficult. In addition, because of this confusion there was an unsolved error in the award system for badges. When trying to make a badge that would reward a person for having so many points, I attempted to use the "has_points" Predicate as described in the Supported Predicates area of the documentation  only to not have that work. After switching to the "completed_some_of_level" method, it worked. This could be because a special type of predicate is necessary for badges, but this is not explicitly stated in the documentation.

The Makahiki system is powerful but it is still in its infancy. For me, this infancy is apparent in some of the ways that the system handles information and control. Besides the above issues noticed in the tutorial done to test the configuration system some general layout and configurations felt like they are between the level suited for a programmer and a development user. For example when making an action, one is asked for a name, a slug, and a title. The relationship between the name and the slug is shown as they fill in together, but the purpose of name is not stated, nor is the limitation unless it is reached (Name has a character limit). When defining points for activities, both the point value and point range is visible, but it is unclear whether both need to be filled in when using a point range, or which take priority when they are. With these and the prior mentioned predicate usage needed (both for badge awarding and unlocking layers in the game), it feels like there is still possible refinements that could be made. Further details and documentation on the predicates, and inclusion of explanations for categories, and things like how priority affects visibility on the grid might alleviate the need to experiment with operations.

Although it is still developing and does have some issues, Makahiki is still a solidly constructed system that can be used for a serious game development. I look forward to seeing what could happen as it is refined and perfected.