My manager just told me that after 12 years of trying to get one of the founders to understand the difference between dev docs and user docs, they tried getting Claude to do it and he finally got it that they are different. He'd been saying this whole time that customer could just read the dev docs. If they could they wouldn't need our software.
I see variations on this too. It's fascinating that there is a class of people who were uninterested in expressive, natural language communication when it was only a way to speak to other people, but who are now super interested in it because it is a way to speak to machines. I worry about the wellbeing of these people -- they seem like prime candidates to slide into AI-induced psychosis.
How firm is the boundary between a dev doc and a user doc in your opinion? I have found that the overlap can be quite large if the users are also technically proficient. Right now I'm trying to balance "how X works so you can use the app better" with "how X works so you can contribute or build your own plugin". DeepWiki really helps as a backstop for anything not already covered though it's not without its own caveats of course.
Not OP but I think you have the right intuition in making a difference between using the app / contribute to the app. You may want to read https://diataxis.fr/ which elaborate on this idea and add another dimension (action / cognition) to this.
Location: Orem, Utah
Remote: Yes
Willing to relocate: Yes
Technologies: Technical Writing, Information Development, User Experience/User Interface (UX/UI), Electronics Engineering, Computer Engineering
Résumé/CV: https://www.linkedin.com/in/stephan-fassmann/
Email: stephan /dot/ fassmann /at/ gmail /dot/ com
There are 2 kinds of documentation: how to make something and how to use something. They are very different.
When you are making something you need to document what it is supposed to do (because the code tells us what it does and bugs are when it does something incorrect). You also need to document why you decided to do it that way so when you go back in 6 months you can pick up more easily.
When you are making user docs you need to think like a user, mainly assuming they never used it before, and they just want to get that task done so they can do all the other tasks they have to do.
Documentation is customer facing because when docs work, customers learn to trust you.
I create documentation that builds trust and help customers use the product successfully. I reduced tech support calls by 60% and increased support website lists by 40%.
> There is nothing special about roman concrete compared to moderns concrete. Modern concrete is much better
Roman concrete is special because it is much more self-healing than modern concrete, and thus more durable.
However, that comes at the cost of being much less strong, set much slower and require rare ingredients. Roman concrete also doesn’t play nice with steel reinforcement.
I think you are incorrect. Compared to modern concrete, roman concrete was more poorly cured at the time of pouring. So when it began to weather and crack, un-cured concrete would mix with water and cure. Thus it was somewhat self healing.
Modern concrete is more uniform in mix, and thus it doesn't leave uncured portions.
We have modern architecture crumbling already less than 100 years after it has been built. I know engineering is about tradeoffs but we should also acknowledge that, as a society, we are so much used to put direct economic cost as the main and sometimes only metric.
You would be very unhappy if you had to live in a house as built 100 years ago. Back then electric lights were rare. even if you had them the wiring wasn't up to running modern life. my house is only 50 years old and it shows signs of the major remodel 30 years ago, and there are still a lot of things that a newer house would all do different that I sometimes miss.
I've lived in a 100 year old house and and in a brand new house, they both had issues. That also both had advantages too.
Oddly the older house had a better designed kitchen. Our lives change over time and our housing has to adjust to that too.
Yes, QA should exist, and should be managed by Operations.
I've been places where devs have no idea what the product-as a whole-does. They just work on the feature of the sprint and throw the code over the wall. Their testing consists of if: it compiled==it passed. They have no idea how to even start actually testing if it's not on the happy path.
I been in places where the code accomplished the spec, but in the most lazy way possible so it appeared to work but was useless outside of what the tests looked for.
I knew one QA guy that was amazing but was so overloaded because management kept hiring "cheap" QA that were actively making his life worse.
I'm a tech writer right now at a tech company and a dev just sent over an LLM generated "doc" that's referring to things that don't exist.
Neither management nor dev has learned anything from Therac-25. QA is hard.
When I was young I took a tour of an air traffic control center near New York. By the end I knew it was not for me. Everyone looked stressed. Things have gotten so much worse.
This guy was doing at least 3 people's jobs even before the first emergency occurred.
Then it was an inevitable cascade failure situation. It was never his fault.
Management failed here. If its stupid but it works, its not stupid, is the old saying, but the reality I've seen is its still stupid but you got lucky. -Maxim 43
If I remember right in many of the outlying areas of England the post people would serve the same purpose, though recently there have been cutbacks so they can't spend time. I also saw an estimate that people are giving $7 Trillion in unpaid caregiving services to family and friends. I'm sure the capitalists would love to be able to tap into that, but they have always been anti-civilization that way.
I set up a computer for an engineering department. It was an IBM PS/2. They wanted to run AutoCAD and Ventura Publisher, one used extended memory and the other expanded.
I ended up making batch files that swapped around autoexec.bat and config.sys files so they could run.
Had an amateur radio friend tell me about a time he found something transmitting interference that looked like a pole mounted transformer but it was upside down and not connected to anything. He reported it to the FCC and it vanished in a couple of days.
Isn't this the expected outcome when someone reports a device that interferes with communications? They find the owner and the device is fixed or removed.
reply