On Tue, 1 Jan 2019 17:34:57 -0600 Michael <mb_devuan-mailingl...@inet-design.com> 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 _______________________________________________ Dng mailing list Dng@lists.dyne.org https://mailinglists.dyne.org/cgi-bin/mailman/listinfo/dng
