Use Timestamps
jankremer.eu
jankremer.eu
Instead, consider making whatever documentation seems useful at a given moment and timestamp it with a clear, prominent “this was accurate on yyyy-mm-dd”. It will still be useful a year later, because people are actually very good at dealing with “ok this detail might have changed since then so I’m not going to let that confuse me when mapping the doc/diagram to the code” kind of stuff.
When things have diverged too much, just make a new one. And timestamp it!
Just put a sentence/textbox somewhere with the date. If someone does a proper update, they will proudly edit that sentence too.
Or it might have had a fuller update last week, but from older information (perhaps going from years old to months old) because it is information that has a high processing latency (like census data). Though in this case the date probably belongs in the text with the timestamp representing the edit date, either way both times should be made clear.
I use this one that allows you to configure the output format:
https://marketplace.visualstudio.com/items?itemName=gieson.w...
If a question comes up later, I can first ask the questioner which date or version of the documentation they are relying on. More than once, the problem has been solved simply by sending the person the current documentation again.
Every project needs someone responsible for someone taking ownership of the documentation, including research and timestamping and the like. Have a todo list where the oldest document goes on top, check it for relevance and accuracy, cull it if it's outdated, get it up to date otherwise, and (as this comment recommends) update the timestamp.
My current project has a wiki going back years, loads of duplicate information, no clues whatsoever if it's still relevant.
This was one of the ideas in the General Semantics philisophy. You don't much hear about it nowadays, it's a pre-war thing. One of the tenants was that you should date expressions. For example, if referring to a person, you'd write "Roosevelt, 1930" because a year later, Roosevelt may behave like a different person altogether.
As for simultaneity we already have to deal with that at the millisecond level. An event logged at 16:00:01.000 as far as LA is concerned maybe logged at 16:00:01.080 in London, or maybe at 16:00:00.920
The difference is negligible compared to leap seconds.
My guess is that planets will keep local day-year. Mars is close enough to Earth that throwing in extra 37 min might make sense. OTOH, most planets and moon might use Earth calendar because local day cycle is too far off human internal clocks.
They will calculate time for other places, but will be less important than time zones since every communication will have light speed lag. No video calls, but lots of email.
1. <https://en.wikipedia.org/wiki/Time_binding>
2. <https://openlibrary.org/works/OL168124W/Manhood_of_humanity?...>
It's usually possible to hover the thing to have the actual timestamp show in a tooltip, but this is so clunky.
Previously discussed at https://news.ycombinator.com/item?id=33446662
For public stuff, dates help others judge whether the information still applies. This matters for most types of information, but particularly technical advice. I write about German bureaucracy and a lot of the information from a few years ago is outdated.
For private stuff, dates gice you a sense of time. A good example is if you've been writing about a weird lump on your neck hurting for over 4 weeks, or realise that you were stressing about the same things a year ago. Sometimes it's just nice to see "on this day" trivia about yourself.
If you have the date, you can correlate data from different sources onto a single timeline. I made a nice project out of that: https://nicolasbouliane.com/projects/timeline
Marginalizing URLs as something that only "people with technical skills" do (and/or should?) care about is no different from any other phenomenon where you take some boring, everyday, mostly unremarkable practice that doesn't involve the use of a computer and then change it where the moment someone gets a whiff of the presence of a computer in the pipeline they throw up their hands and say, "I don't know"/"I don't get this"/"I'm not a computer person".
It's really the doing of both non-technical people and technical people in and adjacent to the modern software industry alike that most people consider URLs gobbledygook instead of what they are: identifiers for a given work. It's especially perverse that the practices of both classes are responsible for most URLs being unsuitable for use Works Cited pages. That could definitely use some fixing, but we do such a poor job (in the US at least) already at explaining, during high school when it's supposed to be covered, the value of proper sourcing and citing that even smart kids come away thinking in terms of superficialities like the rigidity of formats and citation style rather than the actual fundamentals of scholarship. URLs are not exceptional in that regard.
I don't think we can expect URLs to be read in full by people on phones :(.
> You need to scroll it sideways if you want to find something in it.
> I don't think we can expect URLs to be read in full by people on phones :(.
That's because it's implemented inconveniently, a single line. When user taps the address bar, the browser could expand it into an URL editor, conveniently wrapping lines by url parameter boundaries, etc
(A scream goes out)Function before form, always!
The scheme is rather pointless to display in a browser bar nowadays.
And anyone claiming otherwise should riddle me this: How do most non-technical people in the world access "awesomepageireallylike.something"? That's right, they click into the address bar, start typing until the string they remebered appears, and then click on that. And what is that? Exactly: A Google search.
One does not need a technical background to understand URLs.
Browser hiding URLs is like an OS hiding file system structure from users, because files and directories are "too technioal" for them.
Sure he should. But design maxime of a lot of contemporary software does exactly the opposite: Hiding as much of the "icky techy stuff" from the user as possible.
> One does not need a technical background to understand URLs.
That's true, but doesn't change the fact that most people don't. For example, how many people know that the domain of an URL is organised right-to-left? I met people in tech, including programmers, who never figured that out.
> Browser hiding URLs is like an OS hiding file system structure from users, because files and directories are "too technioal" for them.
I agree. And now open a contemporary smart phone interface, and show me, without any special tooling, the actual, "physical" file system. And these things are probably the most successful consumer computing platforms ever.
Yes, I had phones in mind when writting the above :)
> And these things are probably the most successful consumer computing platforms ever.
Users don't have better choice in this market.
What I am certain of, is that it's very inconvenient to not have access to file systems.
Yes, well, this is how mobile OSs behave and most people don't seem to care or even notice...
> Hiding it from users goes against the main usability principle that the user should understand what's going on.
The main usability principle is that the user should understand what matters for them. Seeing the path of the URL is completely useless to 99% of web browsing. Better hide it by default and let power users see it if they want.
> URL is a central concept in web browsing.
Two responses, depending on one's mood:
1. So?
2. Resource identifiers—which URLs are—are a central concept to information science, scholarship, and society and culture.
Aside from the (admittedly often irrational) tendency of some non-technical people to strike a pose of helplessness,* you also end up with technical people making comments like this one: generally taking the stance that it's not too hard to pick this stuff up, with the goal that non-technical people will end up with an appreciation/conception of a URL's technological bones that at least approximately matches the informed mental model of the technical person who is speaking—and who themselves doesn't stop to consider what they themselves have got wrong and are possibly continuing to do wrong by society wrt their role in (negatively) shaping the information architecture of the world around them.
Without a URL, you can't text someone a webpage, refer to it in a social media post or a tweet, or link to it in a document. You can't make links.
Sure, you can browse the web without it. But you can't use any of our everyday basic tools for sharing and content creation without it.
Of course, you should always have the option to see the full URL, but why exactly do you need that clutter on display the whole time? It’s like complaining that the browser renders HTML instead of printing it all as unformatted text.
But seriously, what are you trying to say, that we need to make software match our contemporary physical experience? No, we can do better.
You'd have to search the title of the paper with the names of the authors on the internet, figure out which version you are reading and find out the year of the publication using dblp [1] or finding out in which journal or conference it was published.
Yet, it's so important to actually know when something was written.
With topics like ML and NLP that move fast, even the day/month becomes important, not just the year.
But beside selfish use-cases like looking for an answer to a problem, it is something that was already solved in the previous form of knowledge distribution: books. Why do we always take one step back when moving forward?
Note that with book you have the publication date, but you don’t know when each chapter was written. This doesn’t matter for most books, but for highly technical subjects it may matter.
Notably on the JVM if your locale is en-GB every month is 3 chars: Jan, Feb, Mar, etc. until you get to September which is Sept.
In en-US it’s just Sep.
Of course, if you don’t specify the locale in code, it will choose the system default leading to lovely region specific exceptions for your servers in Ireland and England.
The most nonsensical approach is what the Americans use but let's not go there : - )
Starting with the day or the month is Ludacris.
And if you are using something else, especially if it’s something like XX-XX-XX, specify what you mean by that!
> NOTE: ISO 8601 defines date and time separated by "T". Applications using this syntax may choose, for the sake of readability, to specify a full-date and full-time separated by (say) a space character.
E.g. French has Juin and Juillet, both "jui" start.
Better to just use yyyy-mm-dd everywhere. I see so many bugs from people still using US date format in 2023.
But the whole point of people/companies not putting timestamps on articles and posts is precisely to hide how very old their content is, because they are (rightly) afraid people will click away.
It's not laziness or ignorance, it's generally intentional. So it's not like this advice is going to change their minds.
There is date on the index page Jan - 2016, however it's not obvious from the content page.
I think the argument is that the content should be corrected if it's outdated. So, it shouldn't matter when it was written.
For one thing, people do screenshot/download/archive web sites; these copies don’t get updated, and it can be important to know when they were last updated (as opposed to when the snapshot was created by a third party).
In the end I used Sql Server's SYSUTCDATETIME which is precise to 100 nanoseconds. More importantly I gave all transactions in the batch the same timestamp, added a batch order int column, and a unique contraint on the timestamp, batchOrder columns.
Turns out DateTime.UtcNow is not really designed to give you a precise value for a messaging or transaction system! More of a sometime that day, probably.
Edit: don't trust timestamps, especially from different sources.
Dropping timestamps is very akin to using terse catchy titles, it draws in the unsuspecting and gives content wider/longer exposure.
If it had said "publication date", which is really what's being asked that would be clear enough.
Some examples of software-related landing pages:
https://sindresorhus.com/caprine/ (Caprine app) - shows current version number
https://riot.js.org/ (Riot.js framework) - shows NPM badge with latest version number
... it's not so hard now, is it?
Every blog post should include a human readable date. In fact, this extends to almost anything online and even offline. Timestamps are hard to read.
Use date and time:
Every blog post should include the time it has been created. In fact, this extends to almost anything online and even offline. I was reading Jan Kremers post about blog timestamps and it was not immediately clear to me what time the post was created. Only when I did a look into the HTML source I discovered the time there.
But a non issue to me these days, I moved away from git due to changes Microsoft made after it purchased github. I am back "home" to RCS and anon ftp.
At the very least you should provide the inital publish date and last update.
hello, I'm the shiny new search, and what I offer is that whenever I have found 250 articles that perfectly solve your problem for a search term, I round robin these on the "first page" and you decide which one to choose from the offered ones. This way everyone has an equal opportunity to get some views plus nobody has to do these mating dances to get on the front page.
What a brave new world!
Anywhere a time or date is shown, it should also show corresponding time zone.
It's maddening to see a time in any UX and not know what time zone it's in.
And YES, a date shown on its own needs a time zone!
Genuinely curious as to why knowing the timezone instead of approximate date matters so much.
I am talking about having a UX date/time standard for all of UX, not just blogs.
There is UX where knowing timezone is critical, ex: when analyzing logs, breaking news etc.
To keep things simple it would be great if everyone agreed to always attach TZ info to any date or time shown.
Furthermore, any blog/article that might not appear important at the time it's posted, might become important DUE to breaking news. So just put timezones everywhere an be done with it :)
What other modern browser does this? Tested both Firefox and Chromium and neither did.
For example, sometimes I mostly care about when, in relation to my local time (and in particular how long ago) something was written; other times, the local time of the event happening is relevant too (e.g. “did this happen before or after markets close in the country where it happened”).
new Date(timestampMs).toLocaleString()
Off-topic, but is this a typo of "Nix" or a passive-aggressive jab at Julia for blogging about the tedium of actually getting anything to actual work in modern development?
Probably a lot fewer than you'd think. And certainly not every article you write.
Newsmax reported that PBS knew about the assault on the capitol before it even happened because they put a timestamp on their web page for the Trump congregation when they first published it early in the morning.
They then proceeded to update the page without updating the timestamp, making it look like they predicted the invasion hours in advance
When pressed about this particular time detail, ChatGPT elaborates: While "YYYY-MM-DD" is a common date format, it's not complete for a timestamp, which typically includes both date and time information. A complete timestamp might look like "YYYY-MM-DD HH:mm:ss" to include hours, minutes, and seconds.
So, no, this post doesn't contain a timestamp, and it already fails in its own advice.
However, the post is making the point that the date should be in the post as viewed by the human reader as clearly as possible, which isn't the case in the the referenced post by Julia Evans.
In the third paragraph the author notes that "Only when I copied the URL to complain about it I discovered the date there". So there is no confusion on the author's part about what a timestamp is versus what a date is.
<meta property="article:modified_time" content="2023-11-15T13:40:37+01:00">
<meta property="article:published_time" content="2023-11-15T10:12:30+01:00">> Also, don't make me look for the date. Put the date as obvious as possible, preferably at the beginning of the post.
The fidelity increase of Date->Timestamp for a blog post is almost nothing (unless you are reporting on current events, e.g. the BBC has timestamps in their live reports).
The fidelity increase of {} -> Date is much higher. For tech you now know that this article is likely incorrect. E.g. if it is 10 years old and about how to install Node or something.