edits and publish

www/essays.md

@@ -5,6 +5,7 @@ title: </> htmx - Essays
 
 ## Essays
 
+* [When To Use Hypermedia?](/essays/when-to-use-hypermedia/)
 * [A Real World React to htmx Port](/essays/a-real-world-react-to-htmx-port/)
 * [How Did REST Come To Mean The Opposite of REST?](/essays/how-did-rest-come-to-mean-the-opposite-of-rest/)
 * [Hypermedia-Driven Applications (HDAs)](/essays/hypermedia-driven-applications)

www/essays/when-to-use-hypermedia.md

@@ -1,5 +1,6 @@
 ---
 layout: layout.njk
+tags: posts
 title: When To Use Hypermedia?
 ---
 
@@ -38,25 +39,25 @@ In his talk, [Have SPAs Ruined The Web](https://www.youtube.com/watch?v=860d8usG
 have responded to Mr. Harris' talk [in more detail here](/essays/a-response-to-rich-harris/), but suffice to say we agree
 with him that a pragmatic "Transitional" approach to web development is best: use the right tool for the job.
 
-Where we would likely disagree with Mr. Harris is just where "the line" is between what can be achieved with hypermedia
-and the point at which it is better to reach for a more involved client-side library.  We feel that, with htmx, hypermedia
-can go much, much further than many web developers believe is possible.  And that, for many applications, it can 
-address many or all of their UX needs.
+Where we would likely disagree with Mr. Harris is just where "the line" is between features that can be implemented
+in hypermedia and features that require a more sophisticated client-side approach.  We feel that, with htmx, hypermedia
+can go much, much further than many web developers today believe is possible.  And, further, that, for many applications,
+it can address many or all of their UX needs.
 
 ## Hypermedia: A Good Fit If...
 
 ### _...If your UI is mostly text & images_
 
-In [The Mother Of All htmx Demos](/essays/a-real-world-React-to-htmx-port/), David Buillot of Contexte shows how replacing
+In [The Mother Of All htmx Demos](/essays/a-real-world-React-to-htmx-port/), David Guillot of Contexte shows how replacing
 React with htmx lead to a 67% reduction in the total codebase, along with numerous other eye-popping results.  
 
-As much as we would like to say that every team moving from React to htmx would experience these results, the fact is that the
+As much as we would like to claim that every team moving from React to htmx would experience these results, the fact is that the
 Contexte web application is *extremely amenable* to the hypermedia style.
 
 What makes Contexte so perfect for hypermedia is that it is a media-oriented web application, showing articles consisting
 of text and images for reading.  It has a sophisticated filtering mechanism and other niceties, but the crux of the
 application is displaying and categorizing articles.  This is exactly the sort of thing that hypermedia was designed to
-do, and that is why htmx and hypermedia worked so well for this application.
+do, and this is why htmx and hypermedia worked so well for their application.
 
 ### _...If your UI is CRUD-y_
 
@@ -65,23 +66,24 @@ web applications, in the [Ruby on Rails](https://rubyonrails.org/) style.  If yo
 forms and saving the forms into a database, hypermedia can work very well.  
 
 And, with htmx, it can also be [very smooth](https://htmx.org/examples/click-to-edit/), and not just constrained
-to a simple [detail view](https://htmx.org/examples/edit-row/) approach.
+to the simple [list view/detail view](https://htmx.org/examples/edit-row/) approach many server side applications take.
 
 ### _...If your UI is "nested", with updates mostly taking place within well-defined blocks_
 
 One area where hypermedia can start to go a little wobbly is when you have UI dependencies that span structural
-areas.  A good example of this, and one that often comes up when criticizing the hypermedia approach, is the issue
-count number shown in the ["Issues" tab](https://github.com/bigskysoftware/htmx/issues) in Github.  When you close
-an issue on Github, for a long time, the tab count did not update properly, because the tab itself wasn't replaced
-by the hypermedia request.
+areas of the screen.  A good example of this, and one that often comes up when discussing the hypermedia approach, is the issue
+count number shown on the ["Issues" tab](https://github.com/bigskysoftware/htmx/issues) in Github.  For a long time, 
+when you closed an issue on Github, the issue count on the tab did not update properly.  Github, in general (although
+ not exclusively), uses a hypermedia-style application.
 
 "Ah ha!", exclaims the SPA enthusiast, "See, even GitHub can't get this right!"
 
-Well, yes, but there are [a few techniques for making this work](https://htmx.org/examples/update-other-content/), and,
-if you watch their talk, Contexte handled this situation easily, using events.
+Well, Github has fixed the issue, but it does demonstrate a problem with the hypermedia approach: how do you update
+disjoint parts of the UI cleanly?  htmx offers [a few techniques for making this work](https://htmx.org/examples/update-other-content/), 
+and Contexte, in their talk, discuss handling this situation very cleanly, using the event approach.
 
 But, let us grant that this is an area where the hypermedia approach can get into trouble.  To avoid this problem, one
-strategy is to colocate dependent elements for a given resource within a given region or area on the screen in an
+potential strategy is to colocate dependent elements for a given resource within a given region or area on the screen in an
 application.  
 
 As an example, consider a contact application whose detail screen for displaying and editing a contact has:
@@ -100,7 +102,7 @@ In this scenario, each subsection can have its own dedicated hypermedia end-poin
 * `/contacts/<id>/emails` for the email section
 * `/contacts/<id>/phonenumbers` for the phone numbers section
 
-The trick here is that the email and phone counts are co-located with their collections, which allows you to 
+The trick here is that the email and phone counts are co-located on the screen with their collections, which allows you to 
 [target](/attributes/hx-target) just that particular area for update when a modification is made to the respective 
 collections.  All the data dependencies are co-located within a single area that can be updated via a single, simple
 and obvious target, and that, further, don't interfere with one another when they are replaced.
@@ -110,9 +112,9 @@ all nested within a broader contact detail user interface.
 
 #### A Side Node: UI Driven Hypermedia APIs
 
-Note that our hypermedia API (that is, our end-points) in this case is _driven by the UI_, we have a particular layout 
-that we want to achieve and we adapt our API to that.  If the UI changed, we would have no qualms with completely changing
-the API to satisfy the new requirements.  This is a [unique aspect](https://htmx.org/essays/hateoas/) of developing with
+Note that our hypermedia API (i.e. our end-points) in this case is _driven by the UI_: we have a particular UI layout 
+that we want to achieve, and we adapt our API to that.  If the UI changed, we would have no qualms with completely changing
+our API to satisfy the new requirements.  This is a [unique aspect](https://htmx.org/essays/hateoas/) of developing with
 hypermedia, and we [discuss it in more detail here](https://htmx.org/essays/hypermedia-apis-vs-data-apis/).
 
 Of course, there may be UI requirements that do not allow for grouping of dependent element in this manner and, if
@@ -134,26 +136,25 @@ using this approach is hard to beat for "traditional" web features such as these
 As we discussed above in the section on "nested" UIs, one area where hypermedia can have trouble is when there are 
 many UI dependencies spread across your UI and you can't afford to "update the whole UI".  This is what Roy Fielding was
 getting at in the quote at the top of this article: the web was designed for large-grain hypermedia data transfers, not
-lots of small data exchanges.
+for lots of small data exchanges.
 
 Particularly difficult for hypermedia to handle is when these dependencies are dynamic, that is, they depend on information
-that cannot be determined at render-time.  A good example of this is something like a spreadsheet: a user can enter an
-arbitrary function into a cell and introduce all sorts of dependencies on the screen.  Something like Google Sheets
-would be a poor fit for the hypermedia approach.
+that cannot be determined at server-side render-time.  A good example of this is something like a spreadsheet: a user can
+enter an arbitrary function into a cell and introduce all sorts of dependencies on the screen, on the fly.
 
 (Note, however, that for many applications, the ["editable row"](https://htmx.org/examples/edit-row/) pattern is an 
-acceptable alternative to more general spreadsheet-like behavior, and does play well with hypermedia, by isolating the 
-edits within a bounded area.)
+acceptable alternative to more general spreadsheet-like behavior, and this pattern does play well with hypermedia by 
+isolating edits within a bounded area.)
 
 ### _...If you require offline functionality_
 
 The hypermedia distributed architecture leans heavily on the server side for rendering representations of resources.  
 When a server is down or unreachable, the architecture will obviously have trouble.  It is possible to use Service Workers
 to handle offline requests (although this is a complex option), and it is also easy to detect when a hypermedia 
-application is offline and show an offline message, as many thick-client application od.
+application is offline and show an offline message, as many thick-client application do.
 
 But if your application requires full functionality in an offline environment, then the hypermedia approach is not
-going to be acceptable.
+going to be an acceptable one.
 
 ### _...If your UI state is updated extremely frequently_
 
@@ -162,14 +163,14 @@ example is an online game that needs to capture mouse movements.  Putting a hype
 move and a UI update will not work well, and you would be far better off writing your own client-side state management
 for the game and syncing with a server using a different technology.
 
-Of course, your game may also have a setting page, and that setting page might be better done with hypermedia than
-whatever solution you use for the core of your game.  There is nothing wrong with mixing approaches in the Transitional
+Of course, your game may also have a setting page and that setting page might be better done with hypermedia than
+whatever solution you use for the core of your game.  There is nothing wrong with mixing approaches, in the Transitional
 style!  
 
 We should note, however, that it is typically easier to embed SPA components _within_ a larger hypermedia
-architecture, than vice-versa.  Isolated client-side components can communicate with a broacher hypermedia application
-via events, in the manner demonstrated in the [drag-and-drop Sortable.js + htmx](https://htmx.org/examples/sortable/) 
-example.
+architecture, than vice-versa.  Isolated client-side components can communicate with a broader hypermedia application
+via [events](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Building_blocks/Events), in the manner demonstrated
+in the [drag-and-drop Sortable.js + htmx](https://htmx.org/examples/sortable/) example.
 
 ### _...If your team is not on board_
 
@@ -178,7 +179,7 @@ in favor in web development.  Many companies have adopted React as their standar
 Many developers and consultants have bet their careers on it.  Many hiring managers have never heard of hypermedia, let
 alone htmx, but put React on every job they post out of habit.  It is certainly much easier to hire for r
 
-While this is frustrating, it is also a real phenomenon and should be borne in mind with humility.  Although Contexte
+While this is frustrating, it is a real phenomenon and should be borne in mind with humility.  Although Contexte
 was able to rewrite their application quickly and every effectively in htmx, not all teams are as small, agile and
 passionate, nor are all applications such slam dunks for the approach.  It may be better to adopt hypermedia around
 the edges, perhaps for internal tools first, to prove its value first, before taking a broader look at it.
@@ -187,24 +188,25 @@ the edges, perhaps for internal tools first, to prove its value first, before ta
 
 We are often asked: "OK, so what sorts of applications **wouldn't** htmx be good for".  We prefer to think about
 things on a feature-by-feature basis using the "Transitional" application concept, but it is useful to have some
-broad, popular applications in mind when thinking about just how much might be done in hypermedia versus the SPA
-approach.
+broad, popular applications in mind when thinking about just how much might be done in hypermedia versus other
+approaches.
 
 To give an example of two famous applications that we think _could_ be implemented cleanly in hypermedia, consider 
-[Twitter](https://twitter.com) or [GMail](https://gmail.com).  Both web applications are text-and-image heavy and 
-would be quite amenable to a hypermedia approach.
+[Twitter](https://twitter.com) or [GMail](https://gmail.com).  Both web applications are text-and-image heavy, with
+coarse-grain updates and, thus, would be quite amenable to a hypermedia approach.
 
 Two famous examples of web applications that would _not_ be amenable to a hypermedia approach are 
 [Google Sheets](https://www.google.com/sheets/about/) and [Google Maps](https://maps.google.com).  Google Sheets can have
-a large amount of state within and interdependencies between cells, making it untenable to issue a server request on every
-cell update.  Google Maps, on the other hand, responds rapidly to mouse movements and simply  can't afford a server round trip for
-every one.  Both of these apps require a much more sophisticated client-side setup than hypermedia can provide.
+a large amounts of state within and interdependencies between many cells, making it untenable to issue a server request on every
+cell update.  Google Maps, on the other hand, responds rapidly to mouse movements and simply can't afford a server round trip for
+every one of them.  Both of these applications require a much more sophisticated client-side setup than what hypermedia 
+can provide.
 
 Of course, the vast majority of web applications are nowhere near the scale and complexity of these examples. And almost 
-every web application, even Google Sheets or Google Maps has parts where, potentially, the hypermedia approach could be
+every web application, even Google Sheets or Google Maps, has parts where, potentially, the hypermedia approach would be
 better: simpler, faster and cleaner.
 
 Having hypermedia as a tool in your tool-chest will improve your ability to address engineering problems as a web
-developer, even if you don't reach for it as your favorite hammer, like we do.  There is a 
-good [theoretical basis](https://htmx.org/essays/a-real-world-React-to-htmx-port/) for the approach, as well as 
-[practical benefits for many applications](https://htmx.org/essays/a-real-world-React-to-htmx-port/).
+developer, even if it doesn't become your favorite hammer.  There is a good [theoretical basis](https://htmx.org/essays/a-real-world-React-to-htmx-port/) 
+for the approach, [practical benefits for many applications](https://htmx.org/essays/a-real-world-React-to-htmx-port/),
+and it is "with the grain" of the web in a way that other approaches are not.