I am one of the guys who appreciates docs but also wants pointers at the start.
Just giving me an URL with 50-100 pages of docs is not good enough. Give me something like "when you are just starting", "when you want to tackle a ticket involving X" or "when you need to edit the deployment script" etc.
In my last job the architect was always irritated with me because he wrote a bunch of docs but never organized them or just gave a proper small index -- seriously, just 15 lines of text with links so you know where to click at the start would have been enough! -- but then somehow the team was at fault for "not reading the docs".
So there's a balance. I don't appreciate being given a book and being told "figure it out", which is what happened in my last jobs. Sigh.
Having a small page with starting pointers I always found priceless and is what I do in my work and I've had people contacting me 5 years after I left the job to thank me for it.
my docs are a single page full of one liners for practical issues that have organically arisen several times over the years, with a table of contents at the front.
As I said, I write good docs, but no-one will read them until they have been caught out 3 times asking obvious questions had they gone to the doc first. If I am not around, I know the docs will be abandoned immediately despite it representing a tome of hard won knowledge that saves an incredible amount of aggregate time from never needing to figure out how to do the same task twice.
Just giving me an URL with 50-100 pages of docs is not good enough. Give me something like "when you are just starting", "when you want to tackle a ticket involving X" or "when you need to edit the deployment script" etc.
In my last job the architect was always irritated with me because he wrote a bunch of docs but never organized them or just gave a proper small index -- seriously, just 15 lines of text with links so you know where to click at the start would have been enough! -- but then somehow the team was at fault for "not reading the docs".
So there's a balance. I don't appreciate being given a book and being told "figure it out", which is what happened in my last jobs. Sigh.
Having a small page with starting pointers I always found priceless and is what I do in my work and I've had people contacting me 5 years after I left the job to thank me for it.