SO blog editor here (and author of the piece). Sorry for the confusion, we're republishing our top ten posts of the year over the holidays, and I guess y'all picked this one up again.
Not a great thing to do IMO... by all means resurface the good stuff to the top of the blog, but why change the date? SEO? I don't think there's a good answer?
Since the date is in the URL, you broke old links, and without a redirect at that. You should look into how you "republish" because it doesn't look like you're doing it ideally.
Just some helpful advice. Without a redirect, SEO on the old post will go poof.
I understand if they need to update the date to get it to show up at the top of the blog. But, in that case they can just add a few words to the front of the article saying that they are republishing an item from September.
Yes, that is not cool. By coincidence, a few days ago, I followed a link to an SO blog article, but the link was broken, I searched the article title on Google, which led me... to the same 404 page again. So I took to the great Internet Archive which fortunately worked. Only later have I found that because the article in question was so good they chose to republish it, all original links broke in the process.
URL-Rule 2: permanent (they do not change, no dependencies to anything)
URL-Rule 3: manageable (equals measurable, 1 logic per site section, no complicated exceptions,
no exceptions)
URL-Rule 4: easily scalable logic
URL-Rule 5: short
URL-Rule 6: with a variation (partial) of the targeted phrase
URL-Rule 1 is more important than 1 to 6 combined, URL-Rule 2 is more important than 2 to 6 combines, … URL-Rule 5 and 6 are a trade-of. 6 is the least important.
We used Backstage at a previous company. I was fairly unimpressed- it feels like any knowledge/documentation tool in use at a company where it only works with a lot of discipline to keep it up to date. Curious if others have had better experiences with this
Not Backstage specifically but I think you're describing documentation generally in a company of any size. Some tools are better (e.g. better search) than others. But documentation is something that's (hopefully mostly) correct the day it's created and tends to get less correct over time and may or may not get updated or formally deprecated.
There needs to be a process and probably at least a librarian and even then it's often not obvious. In my experience, a lot of written material gets into the "not quite right any longer but we don't have anything better"--and if you go to update it there's invariably a lot of things that end up getting changed. Not sure I've ever cracked open an old paper or blog post and just changed one thing.
I had an idea some years ago to gradually lower the contrast on the doc page until the users get frustrated and raise concerns/tickets/escalations.
bringing it to a normal contrast again requires a review of the documentation and some kind of punishing if someone just clicks "yeah, it is still fine".
I hate outdated documentation, primarily including mine.
Not sure you'd necessarily need to rely on contrast (or... contrast alone - reader mode and similar might render that not noticeable for folks).
Some datestamp next to multiple areas with a "last reviewed/approved on" info would likely be useful, esp if someone could flag items that are known out of date/wrong/broken for review, even if they didn't know what 'correct' was. I've hit this multiple times as a new person on a team/project - at least those that had moderate documentation. I know "example A" doesn't work, but I don't yet know why it's wrong or how to fix it, but flagging it for review would help me not lose track of it.
I have seen personal blogs where any post that's older than some threshold automatically gets a banner tacked on the top that says something to the effect of "hey, this is an old post, things might have changed since then". Adding something like that to a Wiki seems like a reasonable idea.
Going further, having someone - a librarian role - review entries that are > X months/years old seems useful. So useful that I bet it's probably something people who are 'librarians' in a tech/doc sense probably do. I've just not been in orgs large enough to have people dedicated to that role. And... on day 1, it doesn't seem necessary. I was at a small startup in their year 5, and was initially impressed with all their internal docs, until about a month in I realized huge portions were vastly out of date, sometimes even just a few months after having been written. They were growing so fast "there's no time to keep it up to date!" but I was also often told "just go find X in the docs", yet... if I followed that info, it was wrong. So I had to find the docs and about 80% of the time, schedule a meeting with the author to confirm the docs were, indeed, still "correct". Moderate waste of time, but... "there's no time to keep it updated".
> Not sure you'd necessarily need to rely on contrast
This was just an (extreme) example - what I meant is a way to make the users of the documentation pissed off enough so that they react, which in turn forces the author of the doc to update it.
Yup, in any midsized+ org you need a librarian if you want your doc/kb to be kept in good shape, that person also needs to have a lot of soft power/people skills to enforce rules and procedures many might feel are secondary to their main responsibilities.
My favourite documentation setup was when we decided to go “documentation first” . The entire team would use the documentation every time, and have permissions to modify as they went. We rewarded the “extra time” needed to open the doc and follow/update process every time. (in reality the ROI makes this an easy choice).
There were even cases of printing off doc pages, writing on them while in the field, and updating the digital version.
And it meant that we operated with “one brain” where the documentation always represented the most current collective knowledge.
That's true no matter what. That's the manager's job to enforce the definition of done to include updating documentation, pushing to retire or archive outdated information, and providing a vision and culture of effective documentation. It's not always perfect, but there are tradeoffs in everything.
My last place did a fantastic job in documentation. The culture was established before I was there, and I did bring in the diataxis framework to focus the types of documentation we wrote, but engineers had a good set of documentation to start.
It wasn't all rainbows, but many slack conversations were "I wrote this a few months back - let me know what questions you have."
Whoa hey wait, could you expand on this culture of documenting things? what were the requirements? we desperately need some culture around this, it's been terrible in this remote culture to know what anything is actually about in our codebase
This is probably written better as a blog, so let me put in the highlights and commit to having a blog written by the end of the week at https://ebiester.com - I've written a few things about documentation but haven't addressed it as a cultural element.
The basic assumption is that most developers don't hate writing documentation other than they don't feel like they do it well and don't feel like it's effective. The best way to make it feel effective is threefold - build a proper framework on which you can attach the documentation for discoverability; build an expectation for a documentation portfolio; and build it into your definition of done at the feature level;.
1. Build a proper framework. Techdocs is part of backstage and uses your own git repository to build it in markdown. https://backstage.io/docs/features/techdocs/techdocs-overvie... has more information. Diataxis is a good start to how to think about the types of documentation. https://diataxis.fr/ is what I use to separate out the types of documentation that need to be written. Most documentation in my experience is written as "explanation." Having API reference and howtos are important, and so many howtos are just built out of asking someone on slack anyway.
It is a matter of saying, "you've already done the work to discover this: just put a rough draft where I've put it to be and people can refine it as they go."
2. Build an expectation of a documentation portfolio. I write about that at https://www.ebiester.com/documentation/2020/06/02/agile-docu... but it was a concept written about in Agile Documentation. Start with "these are the minimum requirements for a new project" and keep it very light. Build documentation, codebase expectations, and a quick architectural tour is likely enough to start and the rest will follow.
3. Build it into the definition of done. This takes management buyin, but it means taking it into account for the schedule as technical debt originally. It will not slow you down in the end, but the activation energy of learning takes some time. But just like unit tests or manual testing, there's a set of expectations that are baked into calling something done.
I think a bonus is that so much of documentation is built through our chat and email programs, and just having the courage to copy it out and clean it up a little or take videos and transcripts of debugging sessions is a good start, but it's easy to make a mess. The key is categorization.
I think having the documentation close to the code it documents does make sense though - otherwise it quickly gets disconnected. You just need to create a culture where approval of any code change should also include change to the documentation in the same set of commits.
To a developer, it's unimpressive. To a technical writer with no engineering resources or experience to build their own automation who's used to static site generation or fucking DITA XML, it probably looks like magic, especially the discovery and search parts.
I’ve worked small and midsize startups for a decade+ and the ratio has always been 1/infinity, ie there are zero dedicated writers :/. How common is what you are advocating for? I guess I find it hard to believe 1/5 or even 1/10 companies exist. (Note: I’m not at all saying that’s a good thing )
I've only worked at established companies. My experience was probably exceptional. At my first job, there were 30 SWEs and 4 technical writers. Boy, did that make a difference - both for our customers and for us engineers.
Same here. We had a wiki, only 20% of us maintained the wiki, a manager (a great cloud engineer, but less talented as a strategist) added Backstage, they were the only person that maintained Backstage,
Doesn't backstage offer auto-discovery of docs, ie create docs folder in repo, throw in some markdown files and everything gets picked up?
If so, what kind of maintenance was required?
I think Backstage is better than most tools since it integrates a lot of the functionality in one place. If you have the docs, service map, team data etc in 10 different places it will get worse.
“In my previous role, searching for a library or service’s owner involved looking at Google Sheets or maybe asking around in Slack channels that referred me to other Slack channels. It took me sometimes one or more hours just to find an answer to a simple question about another team’s code.”
This assumes that there is an “owner” of the code, but code usually changes constantly with documentation drifting out of date as soon as the code is changed significantly. Seems like a product manager might have some of this information as part of a functional specification for the last major effort, but even this will be out of date quickly.
This whole problem is organizational in origin. A high level living document should be maintained, especially for APIs that are exposed to third parties. Lack of that document is the fault of management. Not sure how another tool solves that problem.
From what I experienced not a lot of code changes ownership over a period of years. Not saying code always stays at its place. But disagreeing that ownership „usually“ changes with code updates to the code. I do get on board that change in ownership is often a reflection organisational change. Change to often and things fall through the cracks.
I never meant that “ownership” necessarily changes when a small change is made like a game of hot potato. Usually, this is an ad hoc process where the person or people that performed the last major change or wrote the original version are considered to be the “owner” or at the least someone that may have insight into the code. However, typically developers need to accept the reality of figuring out the code on their own since the “owner” may no longer work at the company or they have no recollection of what they wrote 5 years ago.
I've heard zee-shell (like seashell)/zed-shell most often but I don't think there is any nearly universally accepted way like say bash. I've heard both zish and zee/zed-ess-aitch/haitch before but not as often.
I've been pronouncing it as "zeesh" in my head, which works well for me. I think I got that from a coworker? Not sure. Works fairly well with "oh my zeesh" as well, which I like.
The existence of oh-my-zsh has always implied to me a common pronunciation that rhymes with "gosh", which is really the only way their play on words works.
Properly designed, a well integrated cmdb makes tasks easier, faster, and ultimately better. Service Now and sharepoint are great examples of software that aids your tasks when architected properly
