#vss365 today - a primer
It's not magic you know / Never believe it's so
Last updated: November 20, 2023
I mean, coding sometimes feels like magic, so maybe believe it's so?
I have been wanting to write this blog post for a while now, both as a public document for others to reference and for myself to serve as a form of documentation, but have always... not done it. Better late than never, I guess. 😂
Every now and then, I have to correct an incorrectly recorded prompt word on vss365today.com. Sometimes, I see tweets that refer to the site as the source of the #vss365 writing prompt and is randomly chosen by a computer or is where the host posts the day's prompt. As the site has increased in popularity (for example, there are 696 emails sent out every day and were over 3,500 unique visitors to the site between June and July 2022), I feel an increasing need to explain how the site operates and seeks to compliment the #vss365 community.
This post is written in a FAQ-type format to make it easier to understand the information. I plan to keep it updated as information and processes change or as new questions arise. There are some technical references and explanations but I have tried to keep them as simple as possible for non-technical readers. 🙂
General
How does the site fit into the #vss365 community?
I created the site in January 2019 as a way to quickly get the prompt into the hands and minds of more writers more easily. However, it was a selfish reason to start. A writer friend (and amazing college instructor), Dr. B, introduced me and my friends to #vss365 a few weeks before and I really enjoyed it. However, due to the nature of Twitter, it was really easy for me to miss seeing the prompt. Being a programmer, I knew there had to be an easier way to distribute the prompt. As I started creating the site, I realized it would be beneficial to the greater community. So, I put it on the public internet and the rest is history.
#vss365 today fits into the #vss365 community by serving its intended purpose: making the prompt more easily available for writers to find. It further provides a 100% complete archive for every word ever used since the inception of the prompt with a way to quickly search them, which has a variety of uses.
In short, it fits into the community by complementing the community. It cannot and will not replace how the prompt and community operates. Instead, it seeks to assist it in continuing to provide a fun, welcoming, and diverse environment for writers of all skill levels and backgrounds.
Recording & Notifying
How does the site find the Host/Hostess?
I have a list containing Hosts/Hostesses and their assigned hosting date(s). This list is different from the master list in that it only contains the announced Hosts/Hostesses. Every day, this list is referenced by an automatic process (I call it the "finder") to determine who is giving out the words. Whenever a new Host/Hostess is announced, I add them to this list.
However, my list works a bit differently at the technical level. Hosts/Hostess deliver the prompts for set days. Sometimes it is one day, but most of the time it is for multiple days. I need to know what day(s) they are hosting but I don't want to record literally every day. I'd rather use date ranges and deduce the current Host/Hostess. So, how does that work?
Before 2021, that was simple. The Host/Hostess began hosting on the first day of every month. That means I could check who was hosting by simply looking for the person who had the first day of the month. For example, if I wanted to see who was hosting in March 2020, I'd look for the record with the date of 2020-03-01 and get back EdHaiku575. If there was someone who only hosted for a single day (as happened in July 2020), I'd check for the exact day. That means I'd search for the date 2020-07-21 and get back, haha, me! The exact day check would occur first, and if that failed, I'd check for the first day.
With the changes put forth by the #vss365 2021+ charter, there are three scenarios that must be considered to find the current Host/Hostess (although it is still pretty easy to complete):
- Check for a record with the current date
- Check for a record with the first of the month
- Check for a record with the 16th day of the month
These new scenarios now exist because the hosting period has been shortened to 15 days, allowing there to be two Hosts/Hostess in a single month. That creates two possible hosting dates: the 1st and 16th, except during the month of February, when the hosting dates are the 1st and 15th.
The new starting date scenarios are easily handled by checking the current month and day it is, determining from that the proper hosting date, and looking for the record with that date. Checking for the current date remains unchanged.
Where do the words come from?
I probably don't need to write this part but am going to anyway for clarity. 😉
All #vss365 activities occur on Twitter. The prompt's operation is simple.
- A specific person is designated as the Host or Hostess for 15 days in a specific month. The master list of Host/Hostesses is currently maintained and moderated by Levi Krain. Future Hosts/Hostesses are announced in advance so people can follow them.
- Every day during their hosting period, the Host/Hostesses posts a tweet containing the word (sometimes referred to the writing prompt). Only the Host/Hostess knows the word list ahead of time!
- People then write very short stories (hence vss) in any style and genre they wish using the word. Writers typically also use the word for thematic inspiration but that is not required. Any and everyone who wants to join can join! It's not a competition, just a fun way to write something in a very brief format.
How does the site find the word?
At a set time every day, the finder attempts to find the prompt tweet. It starts by making sure a word has not already been recorded for that day.* If it hasn't, the Twitter API is loaded to read the assigned Host/Hostess' tweets to try to find the prompt tweet. If it's found, all relevant information is extracted and recorded in the word archive.
* This is a general assumption. The prompt is based on the premise that there is one and only one word per day. However, this has not always been the case. As of this writing, since the beginning of the prompt, there have been six days where more than one word was given out. Obviously, these additional words should be recorded.
While the finder process runs automatically, it can also be run manually. When run manually, it asks if this is an additional prompt for the given date. If answered affirmatively, the date check is skipped and the prompt is recorded as if one does not already exist for the day. This adds a small amount of work in other places to ensure one or all prompts are correctly referenced but is insignificant to the bigger picture.
How is the prompt sometimes recorded incorrectly?
Computers struggle to understand and interpret language, both the spoken and written form. Without getting into too much technical detail, computers fully lack and cannot possess intuitive thinking. Intuitive thinking is what provides nuance, context clues, and more accurate interpretation of words, phrases, and sentences. Without this ability, computers can only guess what is being expressed.
On the other hand, the grammar and syntax of the written word tends to be more defined. While there is still variety, inconsistency, and evolution of written text, merely extracting words and phrases from the written word without interpretation is easier for computers to do. In the case of Twitter, the #vss365 ambassadors had the insight to require the prompt word to be a hashtag. The prompt tweet evolved to include #prompt to distinguish the prompt tweet from the people using the word in their stories. These things make it somewhat easier to pull out the word.
The finder process identifies the prompt tweet is by searching for the hashtags #vss365 #prompt, in that order. If that combination is found and there's at least one more hashtag present in the tweet, it is assumed to be the day's prompt tweet. This is possible because of the tweet format outlined in the charter.
Next, the tweet's hashtags are filtered against a blocklist of hashtags. This blocklist contains hashtags that should not be considered as a possible prompt, such as #PromptWord or #vss365a (from the VSS365 Anthology Volume 1, which you should absolutely buy 😉).
Once all hashtags are filtered out, ideally, the only remaining hashtags are the identifying hashtags and the prompt word. At that point, we declare success and move on with recording all required information.
Currently, when a prompt word is recorded incorrectly, I have to correct it through changing the data in the database manually.
Why is the prompt repeatedly recorded incorrectly?
There are two likely reasons the prompt word can be repeatedly incorrectly recorded:
- The Host/Hostess didn't follow the required tweet format, as detailed in the charter (typically the issue)
- The finder's blocklist is too restrictive (see the next section)
A Host/Hostess can absolutely have hashtags other than the three the charter requires. The catch is where they appear in the tweet. As long as the three hashtag format is followed, other hashtags work perfectly if they appear afterward. If they appear before, then an incorrect recording will occur. Let me explain with some hypothetical examples.
Suppose I have the following tweet:
Hello! It's always a beautiful day when the inhabitants of vss365 land are writing! 😊 Because of the beauty they create, today's prompt is
🌟 Beauty 🌟
Go forth and be beautiful! 😀 #vss365 #prompt #Beauty
This is a well-written tweet and the finder will have no trouble finding the prompt, "Beauty." The identifying hashtags are present and the format is followed. Most Hosts/Hostess are using this format now, which is good!
Now consider this tweet:
Hello! It's always a beautiful day when the inhabitants of #vss365 land are writing! 😊 Because of the beauty they create, today's #prompt is
🌟 #Beauty 🌟
Go forth and be beautiful! 😀
Do you think this works? The answer is yes! While technically the charter requires the #vss365 #prompt #PromptWord format and that should be followed, this particular tweet won't break the finder. While the three hashtags are not written consecutively, they are still present and in the correct order.
Next, read this tweet carefully:
Hello! It's my turn to host #vss365 and announce today's #prompt! I have always enjoyed the #beauty of nature and love being outside. Everyday is a beautiful day when you love nature! That's why today's word is #Beautiful! 🌻 Go out and write!
This tweet would be identified as the prompt tweet but would record the prompt word incorrectly. The Host/Hostess clearly intended for the prompt word to be "beautiful." However, because the hashtag "beauty" appears first and computers cannot think intuitively and struggle with understanding non-strictly structured data, the finder would incorrectly record it as the prompt.
Consider this tweet:
Hello! It's my turn to announce today's #prompt! I have always enjoyed the #Beauty of nature and love being outside. Everyday is a beautiful day when you love nature! That's why today's #vss365 word is Beauty! 🌻 Go out and write!
This is a troublesome tweet and would cause the finder to completely fail to record the prompt word. While all three hashtags are present, they are not in the correct order. Because the finder checks for the order exactly, it would not be able to determine this is the prompt tweet.
Now you might be wondering, "Can't you make the finder check for the presence of the identifying hashtags, remove them, then pull out the word?" And sadly, no. Without going back over my other post, I cannot intuitively determine what the word could be. If there's only one other hashtag in the tweet then we're good, but what if there isn't? Finally, check out this tweet:
Greetings! I get to give out the #prompt words this time! Fun fun fun!
PROMPT: beauty
The beauty of the outdoors always brings me joy and peace. Hopefully today, you can have some of the same! #vss365 #beauty #tranquility
What is the prompt word in this tweet? I don't know! While actual prompts are much less ambiguous, to a computer, this is an unknown. Even if the #vss365 and #prompt hashtags were removed, it won't be able to determine the prompt word from the remaining hashtags, so it will fail to correctly record the day's prompt.
Could the blocklist be more restrictive to allow more flexible hashtag ordering?
Possibly! The problem here is not if it's possible but if it's sensible. As mentioned earlier, the arbitrariness of the English language makes it hard to truly determine what the actual prompt could be. I also don't know ahead of time what hashtags the Host/Hostess will use. I can only respond to what has already been posted. Additionally, the stricter the blocklist becomes, the greater the possibility that the prompt word itself will be removed, which can cause complete failure (see the next question). A stricter blocklist further restricts the Host/Hostess in how they can write the prompt tweet. Remember, the site's purpose is to compliment the prompt, not dictate it.
For these reasons, the list is manually curated and tailored to the current Host/Hostess, as well as kept as small as possible to filter only as much as needed.
Why is the word sometimes recorded hours after the prompt tweet or not at all?
Besides a incorrectly formatted tweet, failure can occur because the finder did not run at the correct time due to the worldwide reach of the prompt. Previously, I asked each Host/Hostess what time (with time zone) they intended to post the prompt and manually adjusted the finder's kick-off times and restart it.
Starting September 1, 2023, the schedule was changed to run once an hour, starting at 3:05 AM UTC until 12:05 PM UTC.
If the prompt tweet is still not found within this time, I run the finder manually as soon as I have the opportunity.
Finally, failure can also occur because of an error in the code or server downtime. Thankfully, these are rare occurrences.
How are the notification emails sent out?
Once the prompt tweet is found and all information is recorded, an email containing some of that information is created and sent out using the Mailgun service to the people who have voluntarily subscribed to the daily notification emails. In the case that this is an additional prompt for the same day, it makes sure to send out the latest received prompt.
If for some reasons the emails did not send out automatically, like the finder, they too can be triggered manually.
If a word is recorded incorrectly and has to be corrected, the correction is only reflected on the website. It is not possible to change the notification emails once they are sent.
Word Archive
Can I access the word archive myself?
Absolutely! The entire word archive is available to download as an Excel spreadsheet! With it, you can slice, dice, and perform all the word analysis you desire!
How is the word archive file created?
The archive file is generated at the same time a new prompt is found and recorded. The process simply goes through the entire archive and generates a spreadsheet containing all the data. In the case of an incorrectly recorded word, the archive can be regenerated.
Can I have more fine-grained data access?
Sadly, no. While the entire site and finder is powered by an API that controls and handles almost everything, and has been since December 2019, it's not likely to ever be opened up for public use.
Instead, try using the search function. It has lots of options to help you find what you want. For example, the word search supports partial word matches, so searching "ai" will finds all words with "ai" in them. You can also download the complete word archive for more in-depth searching.
Miscellaneous
I'm a programmer! Can I see the source code?
Yes! I am a big believer in open-source development and make all source code to the website and supporting processes available on GitHub.
As a side note, as we increasingly become aware of the privacy-invading practices of social media and other corporations, having the source code publicly available creates accountability for myself and my claims of respecting your privacy because it can inspected at any time to see what is going on. 😉
Thank you
As #vss365 has grown in popularity and involvement, so has the site. It is shared on Twitter almost daily and has been repeatedly referenced by prominent members of the community. I've had multiple Hosts/Hostesses contact me about the site to ensure it stays working and/or to thank me for my service. I even had someone email me one time when visiting the site accidentally displayed my personal website. While I appreciate all of the feedback and am grateful for the positive reception, truly the greatest praise is seeing everyone use it. I have built it up since the start of 2019 in my free (and not so free) time while attending university, working part/full-time, other programming work, and life in general and will continue to do so as long as I possibly can. I operate it at a cost, expecting nothing in return, and hope to not send out a request for monetary assistance any time soon, if ever.
At the end of the day, I thank you, the #vss365 community, for turning this little hobby project into a valuable part of your world. It brings me joy to see you embrace it and that brings me great pleasure to continue to adapt it and make it better serve you and your writing endeavors. Thank you so much. 😊