• Welcome to the new forum! We upgraded our forum software with a host of new boards, capabilities and features. It is also more secure.
    Jump in and join the conversation! You can learn more about the upgrade and new features here.

Beersmith 2.2 - Recipe Archive

tom_hampton

Grandmaster Brewer
Joined
Oct 8, 2011
Messages
929
Reaction score
0
Brad-

Roughly two years ago, I was one of the most vocal proponents of this feature (or a variation of it).  When I saw the announcement, I was very interested to see what you had come up with.  Unfortunately, I think that you have almost entirely missed the mark.  I'm really at a complete loss to understand the logic of the implementation. 

Exactly what can I do with the feature as implemented? 

My first impression is that you did very little, if any, work to understand the "use cases" of the feature.  Ie, what does the user need the feature for?  How will he/she use it?  A simple review of the posts from two years ago would have given you a good starting point for that analysis, and there are quite possibly many more "use cases" than were presented in that discussion.  However, it does not appear that even the points of those discussions have been accounted for.

Here's what I want to do with any change recording feature (note how closely this parallels the features of any soure code revision control system):
[list type=decimal]
[*]Be able to view all changes to a specific artifact in chronological order.
[*]Be able to easily identify the nature of each change to a specific artifact. 
[*]Be able to compare a particular version of an artifact to any other version of that artifact.  All differences should be visually identifiable. 
[*]Be able to undo a specific change to an artifact.
[*]Be able to compare two artifacts, and merge selected differences into a new revision. 

[/list]

Artifacts in the case of beersmith are recipes, ingredients, and profiles.  In the case of these artifacts, it might also be interesting to be able to chart various fields over time. Some examples:
  • Ingredient: price, aa%, potential
  • Recipe: actual OG, actual FG, actual eff
     

Profiles are fairly static once established, so this feature might not be used much...but, you never know!  Someone might find a clever use for it. 

This is not meant to be exhaustive.  Its just an ad-hoc starting point to the design process.  The next step would be to open the discussion up to other knowlegeable designers, and users to try and ensure that the complete spectrum of use cases was covered.  These discussions might ultimately yeild a refined VISION of what the feature should ultimately be.  This vision would them help to triage the use-cases---not to necessarily remove the uses cases from all thought, but to provide some initial focus on what will be done first.  Ideally the basic design would provide a growth path that would allow for the introduction of all known use-cases at some future point. 

So, what of the above can I do with the current implementation? 

[list type=decimal]
[*]Be able to view all changes to a specific artifact in chronological order Kinda, but only at a course level (edit, move, delete).  Also, I can only do that by sorting the entire archive list of changes.  Also, I can ONLY do this for recipes, because no other artifacts are archived (or exposed in the archive UI).
[*]Be able to easily identify the nature of each change to a specific artifact. No.  There is no way to tell what may have changed.  In fact even a simple "save with no changes" shows up as an edit, and it is impossible to tell that no changes have occured. 
[*]Be able to compare a particular version of an artifact to any other version of that artifact.  All differences should be visually identifiable. No.
[*]Be able to undo a specific change to an artifact. No.  Well, kinda...but only if you consider copying the archive recipe back out of the archive and over-write the current version.  That is not really the same.
[*]Be able to compare two artifacts, and merge selected differences into a new revision. No. 

[/list]

There is NO archiving of ingredients, or profiles whatsoever. 

For what its worth, with some planning and forethought the archiving feature described above could have been (re)used to implement the recipe "batch" feature that has also been discussed on several occasions.  The feature sets and use cases overlap almost completely...just on a restricted set of data ("Actual" data, only). 

I'm sorry to post such a negative review.  I was really hoping for much better.  I did volunteer to participate in the design of 2.2.  After significant pointed complaints about your handling of v2.1 over various issues, you asked if I would be interested in assisting in the design planning for v2.2.  You said that you had a focus group or some such of other dedicated users.  I wholeheartedly agreed to participate, and sent you my email address as requested.  However, I never received any emails from you. 

So, I'm left with posting an admittedly very negative review.
 
Thanks
  I appreciate the comments.  How would you envision displaying all of this data  -
  1) You can easily show changes to a recipe in cronological order - just open the Recipe Archive and type a few letters into the search box to show only the recipe you want to see.
  2) Not sure how to show changes to an artifact - for example changing just one ingredient (a grain) could easily change color, IBUs, AA, etc....all at once.  Further, something like a scaling operation may change everything at once.
3) Yes I don't have a compare operation - I can see that might be nice to have
4) You can go back to any change and recover any version - just open the item and copy it to a local folder (or any folder)
5) No - I can't merge revisions but that would be a pretty complex operation since you would need to establish a starting revision as well as which revisions to include in the merge.

Sorry to disappoint you - my thinking was to have a backup feature like time machine where you could go back and recover older versions of a recipe (and see all of the changes made).  This is pretty easy to do from the Archive view using a simple search.  However, I was not thinking of a system that would record and attempt to display every single change made during every edit, as even a simple edit can generate a lot of changes at once.

Brad
 
 
Brad-

Thanks for engaging. 

First, if your goal was simply a time-machine feature, then I largely think that you met that goal.  Obviously, my expectation was substantially different. 

As I said above, I didn't intend this to be an exhaustive list.  Its the type of thing I might take into a early concept meeting with 3-4 other trusted engineers to say, "Here's an idea.  Let's explore where this could go." Ie, its a straw man to get the ball rolling.  Often, some or all of the original ideas are discarded and replaced by much better ones.  Be that as it may....for the sake of the discussion:

My first pass would be that the revision history of an artifact should be ATTACHED to that artifact...perhaps as another page ("History") on the recipe edit form.  This page would show a reverse chronological list of revisions to this recipe.  Each line would be selectable, and various operations would be available: preview (show a print preview), view (show in recipe form editor as read only), compare to current, compare to original, make current (make the current version a revision, and then copy the selected revision to the current version), make new recipe (create a new separate recipe from the selected revision, with or without previous revisions), list all changes (opens a separate dialog listing all changes, one per line). 

To get to your question of how to show changes....Obviously you can't show every edit made between "saves".  But, there should be a happy, medium between "something was changed" and "here is every field that changed since the last save: <field1>, <field 2>" etc.  The question I ask myself is, "What do I want to know if I'm looking at a list of revisions?"  I want to know how this revision is different from the previous revision?  Ie, what did I do to it?  Obviously I CAN do *anything*, but what is typical? 

Typically, I add/delete/modify a couple of ingredients, and maybe change a profile (mash/fermentation).  I usually only change 1 or 2 things at a time.  I save often.  I may even save without having made a change. 

I don't need to know how all the calculated parameters changed.  Sure, my edits will have an impact on several or all of those....but, ultimately I want to know what I *did*.  The secondary effect of that action is of lesser importance for the purpose of recall.

My initial thought would be to limit the basic display to ingredient classes (grain, hops, misc, yeast, water), fields (things like: Name, Brewer, type, etc) and profiles.  I would include action modifiers for each item as: added, deleted, modified. So, an example history might look like this:

versionDescriptionDate/Time
CCurrent VersionNow
3Modified: Grains, Deleted: Hops, Modified: Mash, Added Misc2013-Nov-24
2Added: Water, Modified: Fermentation2013-Nov-23
1Added: Misc, Added: Grains, Added: Hops, Added: Yeast, Modified: fields, 2013-Nov-22
0Original Version2013-Nov-20

The above seems workable, and gives the user some idea about what was done to that particular version.  A more detailed look may still be required for comprehensive/wholesale changes: eg compare to current, previous, or original.  Having a revision history available like this would encourage and reward finer granularity on the users part when it comes to saving.  Ie, the more often you save, the more change detail is available in the history. 

I would envision the "compare to" as using the recipe edit form, but annotating the data that is different between version A and B.  To define some terminology: baseline = the recipe that I'm looking for changes against; target = the recipe that represents the changes.  baseline + listed changes = target.  The baseline recipe is the one that would be completely displayed.  Whereas only the portions of the target that are different than the baseline would be displayed. 

It would take some thought to really see how it works, and probably some trial and error...but, again my straw man idea would be: Value A (Value B).  Or, perhaps a better way:

1.  Display the baseline recipe.
2.  Highlight the parts of the recipe that are different in the target recipe. 
3.  Display the target vales in a tooltip when the mouse is hovered over the field. 
4.  Deletions would be displayed as a strike-through font. 
5.  Additions would be displayed in bold, or some other font. 

It might also be useful to provide a side-by-side comparison tool rather than the overlay described above.  This might use the user selected report format.  If so, it might be able to use a more conventional textual/visual "diff" tool.  But, knowing the format is exactly the same between the two, might allow for some optimization of the compare algorithm.

As I said, previously, once this ability is in place there is no real difference between this system and a system that implements recipes and batches.  The "batch log" is essentially a second revision history with a different name.  The major change is that some of the "actual data" is removed from the recipe object, and pushed into the batch object (while the batch object contains a copy of the recipe).  Then the batch log quickly shows any differences from the base recipe. 

Next there is the meaning of the "version" field to consider.  How that tie into the revision system?  Do you give the user the ability to TAG certain revisions as major milestones in the recipe development?  Can they add a description to that TAG?  Eg:

v1.0 first recipe ready to brew
v1.1 Modifed hops and ferementation profile based on first brew
v2.0 Completely re-did the grains using maris-otter instead of us-2row. Updated specialty grains to compensate. 

These TAGS would be "attached" to a specific revision number. 

Then there is the idea of charting numerical data across revisions, which has applicability outside of recipes.   


 
Back
Top