Last updated: July 30, 2021
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 over 465 emails sent out every day and been over 3,500 unique visitors in the last 30 days), 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. 🙂
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 Arthur Unk. 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 *ahem* 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 interpreation 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 a lot 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
#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.
When the prompt word is incorrectly recorded, it is usually because the filtering step failed to exclude some hashtag(s). This list is manually curated and must be tailored to the current Host/Hostess. This is easily corrected for future days by adjusting the blocklist. Correcting the recording currently requires a manual intervention into the site database but will eventually be possible for me or a trusted few to correct through a (yet to be developed) admin panel.
How 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.
Finally, look at 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.
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. I 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, I tend to keep the blocklist 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, I have to ask each Host/Hostess what time (with time zone) they intend to post the word. I then manually adjust the finder's kick-off times and restart it. To account for the possibility of a late posting, I set it to run four (4) times in the hour following. The first runs 5 minutes after the intended time with the remaining running every 20 minutes. So, for example, if the tweet is to be sent at 12:00 midnight, the finder runs at 12:05, 12:25, 12:45, and 1:05. If the prompt tweet is 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.
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 once a day, 5 minutes after the last scheduled finder run time. If the finder runs for the last time at 1:05, then at 1:10, the archive generation starts. It simply goes through the entire database and writes 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?
Maybe! As part of reworking the underlying code to make the site easier to write and add new features, I have been building an API that provides all the information and features needed. The site has actually been using the API for everything since December 2019. I am working on the possibility of opening it up for public use, but that is still a good way off. I'll be sure to write up a post if/when it happens.
In the mean time, 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.
I'm a programmer! Can I assist in development?
Yes! I am a big believer in open-source development and make all source code to the website and supporting processes available on GitHub. Full development plans are not available online (they are primarily in my head) but I would gladly write them down and making them publicly available.
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. 😉
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 all up over the last 1.5 years in my free (and not so free) time in the middle of university, working, other programming work, and life in general and will continue to be doing so as I enter graduate school next month. I operate it at a cost, expecting nothing in return (although it is possible to donate!), and hope to not send out a request for assistance any time soon.
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. 😊