On Tue, 1 Jan 2019 17:34:57 -0600
Michael <mb_devuan-mailinglist@???> wrote:


> = For an Install Guide I’m against ‘Minimalism.’ My feeling is that
> not giving total, and literally an over abundance of information, not
> only directly inhibits and stops people from doing the Install, but
> also creates vast negative word of mouth from those who attempt the
> Install but can’t complete it because they aren’t given enough
> information to physically be able to follow it.

I agree with you, and HATE ambiguity in documentation, but the
overabundance must be done in such a way that the user's eyes don't
blur over with "oh man I can't do all of that."

I think perhaps the best way to do this is the old presenter's maxim:
Tell em what you're gonna tell em, tell em, then tell em what you told
them. So it might start out with a 1 or 2 level outline of the steps,
then have a section of overabundance now that they understand which
slot to put each action and set of actions into, and finally summarize
it once more with a list.

I was a tech-writer for 8 of my 15 professional programmer years (I did
both and got paid for both), I was the main author of "Samba
Unleashed", I've written 99% of the content on Troubleshooters.Com, and
I wrote a lot of the VimOutliner documentation. It was because of this
work that I came to see things as you expressed: Minimalism in
documentation is stupid, ambiguity sucks, and overabundance must be
done in a way that doesn't intimidate.

Thanks,

SteveT

Steve Litt
December 2018 featured book: Rapid Learning for the 21st Century
http://www.troubleshooters.com/rl21