So whatever the Germans are doing with their rail, thank god the UK isn't.
From what I understand, the problems in the German railway network stem predominantly from growing demand meeting the results of chronic underinvestment in infrastructure. That does not automatically mean that all of the work should be done in big chunks instead of continuously. They still could be doing some things right, and I think it is worth pointing that out. I find it more interesting and productive than blanket dismissal.
As a tech writer people have a lot of experience but they never turn it into institutional knowledge because it’s never written down. Ay best it’s tribal knowledge passed by word of mouth.
I know some people refuse to document things because they are hoping for job security but that never happens. Or sometimes for revenge for getting rid of them. But many companies survive despite those efforts.
There's always a lot of talk about how documentation is important, but there's never budget for a tech writer (well, you must have found some, as you've taken tech writer as a title, but it's not often available) or a documentation maintainer.
Now I work where there is a tech writer and still create internal, dealer, and customer facing documentation, because I am the only one with the knowledge on the subject matter. Some things are filtered to the tech writer so tech writing has been reduced.
Simply, don't call me or contact me for simple questions. Give me a real problem that others cannot solve. Some people like customer service or being able to be the one that helps. Documentation allows me to not be that person and focus on other things.
There is only two ways to communicate to a person on how to use that tool only you created. 1) Showing them how to do it. 2) Giving them documentation so they only contact when needed. Option #2 takes time to save time in the long run that can be diverted else where.
Documentation is part of any product design and software based solution. That new feature time is design, implementation, QA, documentation, and release.
But the things I really need from devs is what is the feature supposed to do and why did you do it that way?
I can read the code to know what it does but often that’s not what it’s supposed to do.
The why can be simple too. We had a dev write an archive delete function that failed but the way was because the CEO pressured him.
I’d love to know what you think documentation means.
Anecdote:
I once (well, many times, but especially this one time) inherited a completely undocumented codebase from a previous "lone wolf", mad genius type of programmer. Most of the stuff he wrote was completely inscrutable at first but really kinda genius once you figured it out.
But one day I was tweaking one of his heatmaps showing solar production on a rooftop from "off" to "a little" to "a lot" to "this is broken", and his color gradient code was a magical one-liner doing strange math as hex operations. It usually went from blue to red to yellow, but would sometimes "overflow" into other strange colors that made no sense. I spent a few hours simulating different edge cases and getting back colors I could not reasonably explain — and which would confuse our users. I talked to my coworkers about it, who mostly insisted "Well, I don't know, but he was a very smart guy, so we should probably just trust him and move on". That was unsatisfying, and didn't really help me close the customer ticket that I was trying to solve.
I kept bugging my boss about it, and after a few days of back and forths and seeing my simulation, he finally agreed to let me reach out to the original programmer (who had long since left the team). I finally got my answer a few hours later. He said, "Oh... that was just some random throwaway gradient I thought looked pretty, lol. I was lazy and wrote it in a hurry and, yeah, it probably bugs out on all but the simplest cases, and doesn't conform to any color standards... glad he caught it."
Sigh, lol... that took several person-days to resolve, when it could've been a simple // #TODO: Use a better gradient system someday
I'd say effective documentation lets the user know enough about the system that they can work on the system without needing to contact the previous person (or people) working on the system. Or at least, so they can get started and only ask 'good' questions.
Something like descriptions of what the system is supposed to do, what it actually does if it differs significantly :D, maybe motivations. Descriptions of the data, and like where does it come from, where does it go, where did it come from (Cotton-Eye Joe?). If the system runs into problems often, a list of common issues and how to fix them, etc.
OTOH, if you commit to not writing documentation, you don't need to write it when the release is ready either. :) I usually work on server side software that doesn't escape my org, though.
Broadly speaking you are correct. Expertise like mine is rare and fleeting mostly because you can only really build it long term by working at a company which can convince international clients to take them on. Even large countries tend not to have more than a handful of trains being built on any given day of the week.
This is one place where having a business located in a nation long known for its relative neutrality, calmness and international trustworthiness can pay off. All of the Nordics are good at this, really.
Nobody had built a nuclear reactor in ages. The last ones were from the 80's and this was a completely new technology (EPR). There was no institutional knowledge.
It didn't help that the French attitude to building was to "just slap it up real fast up north and use it as a reference to get REAL customers". They didn't figure in the fact that STUK (the Finnish radiation authority) is _really_ fucking good at what they do and don't cut any corners for any reason resulting in the French having to build many parts twice because the first attempt was subpar.
[0] https://en.wikipedia.org/wiki/Olkiluoto_Nuclear_Power_Plant [1] https://en.wikipedia.org/wiki/Radiation_and_Nuclear_Safety_A...
Once large infrastructure projects become sporadic in nature, you begin to run into issues.
The solution has to be continuous stimulus, but that also runs into problems of corruption and capture by special interests (the longer the stimulus, the more incentive there is for 3rd parties to appropriate funds).
> some online ID law
Texas and Utah in the US also have similar online age verification laws. Texas is the second richest state in the US by GDP per capita, but even that was not enough.
All the old money already got a ton of wealth they didn't really deserve (conquest through Native american genocide)
It's one of the most consequential problems imaginable to solve, particularly as the US begins to realize that we need to compete with decades of China's subsidized energy and industrialization/manufacturing capacity.
Taking it a level deeper, what most don't realize is that infrastructure is an asset class: before someone funds the construction of $100M of solar technology, a developer will spend 2-5 years developing 15 or so major commercial agreements that enable a lender/financier to take comfort that when they deploy such a large amount of cash, they'll achieve a target yield over 20+ years. Orchestrating these negotiations (with multiple "adversaries") into a single, successfully bankable project is remarkably difficult and compared to the talent needed, very few have the slightest clue how to do this successfully.
Our bet at Phosphor is that this is actually solvable by combining natural language interfaces with really sophisticated version control and programming languages that read like english for financial models and legal agreements, which enables program verification. This is a really hard technical challenge because version control like Git really doesn't work: you need to be able to synchronize multiple lenses of change sets where each lens/branch is a dynamic document that gets negotiated. Dynamically composable change sets all the way down.
We are definitely solving this at Phosphor (phosphor.co) and we're actively hiring for whoever is interested in working at the intersection of HCI, program verification, natural language interfaces and distributed systems.
We just do subways and get good at it.