Change the guide's title to be task-focused
rstoyanchev opened this issue · comments
The current title "Messaging with STOMP over WebSocket" is an accurate description. However, one of the major benefits of the GS guides is their task-focused nature. Fro that perspective I'd like to propose a change.
If we take a step back from the specifics of the technical solution, I believe the task of interest is adding real-time behavior to web applications, or more specifically using WebSocket to add real-time behavior to browser applications. I believe this is a much more instantly appealing topic that also passes the "would anyone google this?" test.
Following that line of thinking, the opening paragraph is too much of a leap:
This guide walks you through the process of creating a "hello world" STOMP messaging server with Spring.
A natural reaction would be: wait a minute, you haven't told me what STOMP is and why it is relevant to me.
Indeed the guide cannot afford to make long explanations, but we can keep the introduction relatively short and simple, yet meaningful. I've explained it enough many times by now in talks and presentations and I believe this line of reasoning resonates reasonably well:
=> websocket is a standard for two-way client-server communication over the web
=> it's great but you need fallback options (IE 7/8/9) and its too-level...
=> it's comparable to using the Servlet API (custom Servlet app anyone?)
=> except it's even lower level than that -- while Servlet API is built on HTTP (an application-level protocol over TCP), the WebSocket protocol is a very thin layer above TCP -- a stream of bytes broken down into messages and what's in these messages is entirely up to you
=> this is why WebSocket defines the use of sub-protocols (i.e. higher-level protocols) on top
=> STOMP is a great match, a simple messaging protocol (frames inspired by HTTP), widely used and supported
=> etc.
I'm happy to help refine and distill this.
Good stuff, @rstoyanchev. Whatever changes we come up with for this, we should also propagate them over to the msgs.js variant that I'm hoping to get to a first complete draft state today.
I rewrote the title and descriptor. Waiting for the caches to turn over.
Thanks Greg. Does that change the guide's title though? That was the point of this issue and I don't see that from this commit. I also suggested a slightly more detailed introduction that sets up the stage as briefly as possible.
No, I also edited the title, or rather, the description, sine it was overloaded on STOMP, which the reader hasn't gotten to yet.. The title isn't managed through version control. Instead, it's embedded in the description at the root of the repo: "Messaging with STOMP over WebSocket :: Learn how to the send and receive messages between a browser and the server over a WebSocket".
I'm not sure about real time, because that term actually has some precise meaning. I was thinking along the lines of 2-way communication between browser and server.
I see.
Still though having STOMP in the title (and intro) is precisely what my point was about. It's technically accurate but it's dropping a term that isn't familiar to most. The title should stay task-focused reflecting what a developer is looking and I'm pretty sure it's not STOMP. So the key question is what is the task?
I think one large group of developers have heard about WebSocket and are simply curious to know more in which case "Building WebSocket application" or "Adding WebSocket to an application" is adequate. A smaller group will have real application requirements for building low-latency, high-frequency, event-driven web applications (e.g. finance, games, collaboration, etc). Adding all that of course is a mouthful and there could be other simpler ways to suggest it such as "Building a WebSocket-style application".
By the way what is the precise definition of real time that you have in mind? Maybe "real time web" would be better?
In any case I don't insist on real-time. Something simple like "Building a WebSocket-style application" would be effective.
I did graduate research on real time systems. Real time systems have deadlines and tolerances, some soft, some hard. Think about an app that controls a bottle capper on an assembly line. Or software controlling a telescope with a camera tracking the rotation of stars. Both of these require that real life components respond to control signals within certain time frames or the end product is ruined. That's why websocket technology isn't exactly "real time" because we don't impose any type of deadlines.
But to further your point, yes we should drop STOMP from the title/description. Since we are about to add categories that are also searchable, we can make up for it there, in case people want to search on it nonetheless. Perhaps we are looking for interactive web apps? "Building an interactive web application with WebSocket".
Web apps have had a long standing history of click-and-wait for the a new page. WebSocket smashes this up by making the site more interactive. AJAX made that possible, but WebSocket steps up the game.
Yes that's along the lines of what I had in mind. Perhaps "Using WebSocket to build an interactive web application"? Same wording, just putting WebSocket to the beginning.
@rstoyanchev Check out the updated guide now and tell me how it reads.
@gregturn, thanks for taking care of this. I did mean to comment but am swamped till tomorrow. I wanted to submit a pull request with a few minor updates.