I'll get things working locally first, but I always have to test it in docker/other fresh test env (Vagrant), just to be sure I haven't committed the same sin myself.
My ideal state is that for my kind of .NET work, it should be sufficient to simply install the latest Visual Studio, check out the Git repo, and press "play".
That's not always possible, so then the exercise becomes to simply document each step, ideally with both English words and a CLI snippet.
But there's also that your language to the user doesn't necessarily say what you think it does. You can't read it from the position of someone new. Only someone new can.
And a set of commands to paste to CLI isn't the full extent of what we usually mean by documentation.
I am a big fan of the "clone, F5" and it should run. If specific steps are required, I put that in a setup.ps1, and the details in the readme.md.
If the project has external requirements, I put a link to the repos, which should all be... "clone, F5"...
The golden rule: Plan -> Act -> Test -> Repeat
Writing documentation is hard. Start with: Who am I writing this for?
edit: I may have misunderstood OP's "with minimal expertise" for "total beginner". They're two different things, absolutely.
In other words, people who are used to reading docs can read (good) docs just fine.
Yes, of course, good docs are a must. They are critical to success. But not all docs have to explain how to use a right-mouse button.
And just as many where people explain in detail exactly how to do foo with bar without explaining why I would want to do foo in the first place and what a bar even is.
My mom taught CS in the 1980s, and told her students on day one: "Computers are stupid, they will only do exactly what you tell them to do, not what you want them to do." Program code is, in a sense, a tutorial for an utter beginner. The benefit of coding is that you can do the "beginner test" over and over without wasting anybody's time, so you know that the computer will get through it. But an expert (including yourself) might read that code and never see that it does or doesn't work.
On lesson I've learned from that: It's a lot about managing confidence of the user.
To do this, the instruction of "invoke this shell command" is now usually accompanied with a number of sections collapsed by default: How does a successful invocation look like - especially if it contains "ignorable warnings"? What errors could occur, and are they fatal or can they be fixed on the fly? Some more complex shell-stuff is often also accompanied by an explanation of what all of this is.
And yes, this means that sometimes one step in a runbook has a page of documentation if you read it all. But we've found that this helps a lot during onboarding new team members, as by now, a lot of the standard runbooks are also a prety good introduction to the quirks and quarrels of the normal tools we use.
It saved me a whole bunch of headaches for when other users get enrolled in these workflows.
Unfortunately some of the production people aren't comfortable enough pushing for changes in the documentation so some of my job now is to ask what they've noted and get it added.
Guess what humans hate to do? Especially the smart ones, which of course you want to employ on your helpdesk? They just would not read the damned instructions.
I think this was because many of the instructions were dumb. We were explaining decades-old bank stuff. It didn't make sense, but it's what you had to do! So these guys tried to 'fix' it, and in doing so, broke it.
The whole support model was predicated on this idea that the 3rd level guys would write stuff that the 1st level guys would slavishly follow. It never worked.
> Users don’t have the manual, and if they did, they wouldn’t read it.I honestly thought this was some sort of trick exercise to see how I deal with broken processes, and I was writing fixes to their docs and shell scripts to deal with error states, and reported back to the person. I initially got a 'no, this isn't that sort of test. the docs work, just follow them'. After more back and forth, I got 'oh, I see that might be broken, yeah, just carry on'. I fixed what I could, made a couple commits back up, but was then told my commits needed more context, which I then added, and promptly never heard back from them again. Until... weeks later, HR reached out to say "we've gone with someone else". I recounted this story and got at least some semblance of feigned shock of 'that's not how any of this is supposed to go'. I'd kept some screenshots and emails, but they didn't care to go down that road.
tldr - Employers giving tests, please run through your own exercise processes now and then (or maybe even automate them with some smoke tests).
I do think a lot of developer tutorials and documentation don't take into consideration that many people might not have a common understanding of terminology especially if the reader is coming across this problem or process for the first time.
In contrast, the Java ecosystem has been really bad at documentation in my experience. Most of it is just explanations of function signatures, without any words on how those functions work as a whole system. The situation is even worse on Android, where there are dozens of standard APIs to achieve the same functionality.
> Those are references, not tutorial.
This is a great phrase. I fully agree with your sentiment. To me, I never read Javadocs in HTML-only form. I always read them in an IDE, along with the library code in question. If anything is unclear from the Javadoc, then read the code (which immediately follows the Javadoc).But as library users, we're generally not supposed to have to learn the system from its source, aren't we?
... which in practice means, particularly for stuff that recently changed, that you go to StackOverflow only to find out that the majority of posts are horribly outdated and don't even compile any more.
The other side are code examples that technically work and show, say, the syntax on how to use a programming language's or framework's shiny new feature... but manage to dumb the code example down so far that one has a very hard time wrapping around one's head on how to use this feature in a real world application.
So no, Those aren't just there to refresh developer's memory. In many cases, they are the only resource for learning the system from scratch.
From a software engineer standpoint, we have a larger collection of docs for the internal platform we run. The docs for other engineers follow the diátaxis framework [0] for documentation. Its the best approach we've found so far and the overall questions and guidance my team needed to provide reduced by a significant margin while the PRs we know receive have increased in quality and quantity.
> never be able to grow in their role and move up to tier 2. I'm not sure how to solve for this problem.
I have a selfish answer. Who cares about staff that don't improve. Really. Read that twice. Leave them behind in the dust. I am always blown away when I meet someone in my career and they have been doing some shitty support role, and they have barely progressed (career-wise or tech-knowledge-wise). Who are these people? Everyday, they dig a hole, then a 4PM they fill the hole. Rinse and repeat! Someone who is smart enough to "figure it all out" and write docs should be promoted, or moved to another support team to repeat the same pattern.It’s easy to say who cares and hire from the outside, but that organizational context and care for support is lost. People build whatever and throw it over the fence, which makes everything worse, imo. Those people also tend not to stick around, so they have no skin in the game and it’s hard to develop culture as people rotate in and out frequently.
There are always some people who will never learn, and these people are cheaper, but there are other hidden costs as you seek to optimize for low-skill workers.
Fixing and updating the README when I join a new team and set up their dev environment is always extremely well-received.
Updating docs in source control also onboards folks to code review. It would be weird to update docs and get a hostile reception.
While nice to walk through with someone and conduct a usability study, just leave it better for the next person (who could be yourself, if you forget). That has happened before.
You need to be brutal with yourself for this, and understand you're chasing popularity, and not necessarily revenue.
It's good to be popular with your users, but if your users are not your customers...
> I've used FAANG docs that don't come close to passing the above criteria.
... FAANG is an excellent example of which; Because their documentation and code is so bad integrations always take longer than anyone can estimate, this actually discourages managers from considering a second integration.
That is to say it's not necessarily good business to "pass the above criteria" and I think it's important to remember that.
An important point easy to lose sight of when writing when that knowledge isn't lost yet
Most cases it is not that docs author forgot users wont have same toolchains. Simply do not bother reducing config files to share just source code. Indirectly pushing users to make use of same tools.
Hopefully in 20 years no one will be going to check the source code of anything, and programming is elevated even more.
50 years is crazy amount of time, to stay this primitive. Tech shouldn't just evolve for end users.
The status quo is a moving target. 6 months ago what you said would be fully correct. This is no longer the case, now you are only sometimes right and mostly wrong. It is getting better.
Yesterday, Google's AI told me that "Senior Brown Water" was the original but rejected name for the soft drink "Mr. Pibb", and presented that as factual data. I took a screenshot.
Somehow the foundational large language model of one of the largest corporations on the planet cannot distinguish between reality and a rerun of the 2007 sitcom "Scrubs."
Watch someone play the game for the first time. Don’t interfere. See if they can figure out how to play.
I think an intense culture of playtesting is why valve software puts out games so rarely. Their new strategy seems to be to keep a title semi-secret for years while a small army plays it full time. If Deadlock makes it to market, it is almost certainly going to be an acceptable game to most who are even remotely interested in the genre.
Nargflargler: Flargles the narg
You need to do something besides repeat the name in the definition.I hate how this looks "accessible" to people in theory, but in reality finding those screens is more like playing a hidden object game.
Also, I hate how those things keep changing around in all kinds of software, but especially Apple. Somebody probably thinks "yeah maybe we should move the Fargler settings from the Narg to the Birp screen", and makes dozens of internet "documentation" (and sometimes their own!) obsolete.
setFontSize(float): sets the font size.
Cool. Sets the font size in what? Points? Pixels? Device-independent pixels? Which of the 12 different types of measurement Android supports is used here? I can’t remember exactly what it turned out to be, but I know it wasn’t the unit I expect for fonts (points).It's a widespread issue though, where the API designer doesn't clearly communicate either what the thing does and/or what the thing needs.
duration_ms = 1000
you can have
duration = 1s // or duration = Seconds(1) in deficient languages
and it's either a compile error or the type system enforces the correct conversion.
As for the bad rap of hungarian notation, it's mostly from people using it to encode something that is already clear from the types. "fDuration" helps no one over just "duration".
The biggest problem is that this ends up creating so much extra work. An extra 2 seconds from the dev could save hundreds or even thousands of people hours of work. I can't tell you how many hours I've spent chasing stupid shit like your example. I don't know a single programmer who hasn't.
I just don't understand why everyone's frustration with documentation (or lack of) doesn't make obvious the importance of good documentation. Every single one of us has experienced the wasted time and effort that results from the lack of documentation or from low quality docs. Every single one of us has also reaped the benefits of good documentation and seen how much faster it makes us. How does anyone end up convincing themselves that documentation is a waste of time? It feels insane
Self documenting code in this case would mean using a type that encodes the unit - which would have the additional benefit that the compiler or other tools can now check correct usage.
Requiring docs isn't the cause of the problem. It's the lack of enforcing quality. The difference is that you're looking at the metric and seeing Goodharts Law in action while there's nothing preventing you from going beyond the metric. That's the real issue is that metrics only take you so far. No metric can be perfectly aligned so it's up to the people who are evaluating the metrics to determine if the letter of the law is being followed or the spirit of it is. If you do the latter then yeah, maybe some functions will be left without docs but you also won't hasn't those tautological docs either. If you only care about the letter of the law then you should expect the laziest bullshit as Goodharts Law always wins out.
Stop reading too much into metrics. Metrics are only guides
Not in general, but here it could be called:
setFontSize (dvi_pixel_t size);A structure that defines a metadata key space.
source: https://developer.apple.com/documentation/avfoundation/avmet...
What are you expecting the documentation to say here? It will make more sense when you find where it’s used.
Edit: First link on the bottom explains exactly what it’s used for. https://developer.apple.com/documentation/avfoundation/retri...
There’s plenty of other poorly documented Apple APIs (io_surface), but this isn’t one of them.
And if you’re reading the documentation because you do development, then you would already know that the header files are installed on your computer and you can trivially verify that there is nothing to document because it’s just a query key.
Going off to read the header file means it isn't documented.
Sounds like something that should be mentioned in the opening sentence of https://developer.apple.com/documentation/avfoundation/avmet...
My own bete noire here is MSDN. It's full of overloads like "Foo(string parameter, FooOptions options) - actually useful documentation. Foo(string parameter) - does Foo with default options." But to find out what the default options actually are, you have to find another page, probably the FooOptions constructor. I wanted the default options to be mentioned on the "Foo(string parameter)" page, and they so rarely are. (A few pages are better, thankfully).
It's better for maintenance (of the documentation) if the default options are only described in one place. (If the defaults change in a new version, this ensures the documentation doesn't have inconsistent, wrong descriptions. The analogous reasoning, applied to the code, is probably part of why the FooOptions class exists in the first place, after all.) But they should do you the courtesy of linking there.
Hell, I even do this on my github.io website that uses markdown. You can just write some text in one document and read it in another.
We're programmers, so we should be lazy. It's about being the right lazy. You can be lazy by putting of a task today that takes more effort tomorrow or you can be lazy by doing a task today that takes less work than it would take to do tomorrow. Most people choose the former and wonder why they have so much work. In programming if you're doing redundant work then you're probably being the first type of lazy
MSDN even uses those, a lot. But not enough. I wish that every time they had a "Foo(string parameter) - uses the default FooOptions" it was a link to the documentation section where the default FooOptions are listed. But usually you're left to find the default FooOptions yourself, which means 5-10 minutes of digging through docs (1-2 minutes if you're lucky) that I could have spent writing or reviewing code instead. That adds up.
I've basically resigned myself to "it makes sense in Redmond somehow, even if it makes no sense to me."
Rant: if you want antialiased text, you need to use Direct2D. Direct2D is one of those APIs that waste developer's lives. You have to allocate your own framebuffer, for crying out loud. And then, you have to reallocate it if it ever disappears for some reason, and the docs don't tell you when this might happen (hot swap a video card? change monitor resolution? User moves window to a monitor with a different video card?).
I found this out developing a cross-platform UI library, https://github.com/eightbrains/uitk, leading to my above conclusion that the only proper way to relate to the Microsoft API is through some layer.
I have to assume that there exists some language where that relationship is described in one word, but it hurts my English-oriented brain.
Some of the East Asian languages are crazy regarding terms for family members. It's like learning foreign words for plants: I just give up. I will not even attempt to learn them.
dont say.. boop?!
> A prepositional phrase is a phrase with a preposition in it.
> A preposition is a word in a prepositional phrase.
Lives rent free in my brain.
a) it needs namespaces
b) but giving people namespaces is unironically bad because it's what lead to "enterprise development" style APIs like C# where everything is named System.DataStructures.Collections.Arrays.Lists.ArrayList, as if giving something a longer name makes it more professional.
c) so instead two letters means a system framework and three letters means a user framework
In other words, my only complaint is that this Apple convention is not more easily discoverable. Or perhaps that the expert author of the book I was reading (this was back in the day) didn't feel the need to share it with his readers.
There’s a version for kids to show the details of how to program by literally interpreting steps. https://youtube.com/watch?v=n4rh2jD8OkY
And if you have access to user experience researchers, go talk to them! They are experts in running this kind of scenario, and can help you avoid all the pitfalls that might bias your results
Sounds simple, right?
I ran usability tests at a past company and have seen people who were incapable of blurting out explanations, pointing at the screen, even audibly grunting or whining to themselves when the participant made an incorrect guess about what something meant. One even grabbed the mouse.
Having a neutral moderator can help as it allows the people who made the UI/docs to stay on mute or on the other side of one-way mirror.
But I'd still suggest learning the "just watch" technique. If you master that and wish to take the next step, look up "think-aloud protocol".
Yeah, because it's wasting my time having to watch people who literally have never heard of something as basic as keyboard shortcuts. It's fine if I actually have the time to explain to some Gen Z kid how Ctrl+X/C/V works, but being forced to sit around and watch someone with that level of non-understanding of how a computer works when I got a full backlog of shit to do is just agonizing.
With a video recording, I can at least go forward and see where they actually have problems with stuff that is in my influence and skip over the utterly boring moments that are just wasting my already limited time.
> wasting my time having to watch people who literally have never heard of something as basic as keyboard shortcuts
First it depends on whether the audience for your product includes people who do not know keyboard shortcuts. If that's not your target audience then the rest of the test may not be valid anyway.
Otherwise, there is utility in forcing yourself to watch your users struggle with your product. The best product developers/owners I know have a bottomless appetite for observing people use their product, even if doing so means deferring the rest of their "full backlog of shit". Perhaps they're less efficient in the short term at churning out lines of code, but the understanding and empathy they develop makes them significantly more effective in the long term.
If you are a master of UI/UX and you are observing a user doesn't go through the paths you've created its an opportunity - you might be able to learn something that would make your approach more successful across a host of different users that up to this point you clearly are not winning the game against.
If you take an antagonistic approach and curse the idiot for making you watch you have not even put on a jersey yet.
If you let someone flounder on one task indefinitely then you don't learn anything about subsequent tasks. But if you correct them too quickly you won't uncover the other approaches they would have tried to complete the task. Most research plans define cutoffs such as:
1. Participant expresses extreme frustration or gives up
2. A couple minutes have elapsed from the first failed attempt
3. Participant unsuccessfully attempts three distinct approaches
If the test reaches one of your cutoffs then the interface/docs have failed the task and the moderator can skip to the next task or question. Sometimes they'll also offer to show the participant the expected solution or explanation.
Okay, but GP is talking about tutorials, which are a completely different form of documentation.
Then, the engineers are expected to write the docs in between these tickets, and doc is seen as something "to be done within 30 minutes" - of course the docs will be comically (or tragically, depending on your perspective) bad.
Most people have 0 idea on how to write good docs, so in 30 minutes, they write stream-of-consciousness docs and return back to the ticket hell.
>> My current role is standing up a new devex team which I'm hoping turns the tide here.
I'd love to know what you're doing different that can help with this problem. Writing more, new documentation is unlikely to be it.
I’ve always advocated for new employees first contributions to be fixing problems they had in these setup materials. They are coming in with fresh eyes and no context so they are the best possible reviewer
Trying to follow the docs, supplementing with a lot of googling, I somehow managed to remove the tar program from my system. This broke literally everything. Had to stop halfway through the multi-day process to do a clean reset and start over from scratch.
Suppose they get stuck on the first step in a multistep procedure. Do you just let them keep flailing on that step for however long they are available, so all that you learn from that entire session is that the first step needs rewriting? Or do you end the test and let them go, again learning nothing beyond that the documentation for the first step sucks?
Wouldn't it be better at that point to help them on to the next step and then continue on having them test the rest of the steps?
The problem is not the docs, it's Conway's law. One team designs the API, the other team designs the portal, and another team designs the SDK. The user has a holistic experience that cuts through each team.
That, and the docs are usually written first by the most technical person around, who has a hard time sharing the world view of a noob.
The first thing I noticed when I joined was the culture of "Please ask when something is not clear". After was given a quick overview in person.
You guess: almost everything is unclear. A mess. Need to ask a lot. Task descriptions, purpose, reasons, whys, wheres, what does this comment mean, why are these things contradict each other, and so on, and so on.
And except asking KG, usually the answer is: ask XY. Or KG.
People always busy, always in rush, give a condensed answer raising the same amount of new questions that it answers.
When KG is out, productivity slows down.
And all this beyond the usual in a meeting, out with customer, on holiday, sick, the children is sick, held up in a traffic jam, car broke down, need to finish project P so schedule something for next week, and all those kinds of common things making the relevant person unavailable when "something is not clear".
And beyond the forgetting 4 things of the 15 new info given by the time we are finished with the converstaion. No written trail to look back at.
When 3 person paint a complete picture then all above happen three times in a row, or in a never ending loop.
Productivity suffers, quality suffers, I will leave as soon as I can.
Positive things? Probably that the expectations are low. And they pay well. And by now I am irreplecable in a local subset I was hacking together (I do not call it work or development), not even KG can help others there! I will leave on my own terms (as usual, unluckily).
Might not this loop be invoking Goodhart's Law?
What is "address each one": are we just changing that document, or are we (also) changing something in the system that the document is about?
If no newbie has any problem following the document, is that still a good document for non-newbies?
If no newbie has any problem with the system that the document is about, are there any downsides?
If the user achieves what they need with minimal stress/guesswork/ambiguity, the docs pass. If not, note every single place they fail, address each one, and repeat with a new user.
I've used FAANG docs that don't come close to passing the above criteria.
I've been incredibly grateful my org set this high bar. Especially when using docs for critical tech that I only use from time to time (where I forget lots of it). It saves meetings, support inquiries, and video calls, because the user can self-serve.