Re: [DNG] What should an Install Guide accomplish?
On Wed, Jan 02, 2019 at 06:39:57PM +1100, Ralph Ronnquist via Dng wrote: > Concise is perfect, if comprehensive, within reason. And, perhaps gilded > by a (growing?) collection of links to "user stories"? > > Ralph. > +1 I would just recommend one single thing: KISS. Most users tend to *not* read documentation at all. Actually, the more documentation you provide, the less the documentation is used. Moreover, the less experienced a user is, the shorter the time and the smaller the attention they will normally put into reading docs. This has been proven time and again by the very same simple questions being asked here, on IRC, and on dev1galaxy (one example for all: "What is the default root password in the Devuan live images?"), while those questions could have been avoided by a quick read through the Release Notes or the README.txt file accompanying each iso. If we need to have an install guide, let's just put images and short comments in there, IMHO. Most of the rest will be ignored anyway. My2Cents KatolaZ -- [ ~.,_ Enzo Nicosia aka KatolaZ - Devuan -- Freaknet Medialab ] [ "+. katolaz [at] freaknet.org --- katolaz [at] yahoo.it ] [ @) http://kalos.mine.nu --- Devuan GNU + Linux User ] [ @@) http://maths.qmul.ac.uk/~vnicosia -- GPG: 0B5F062F ] [ (@@@) Twitter: @KatolaZ - skype: katolaz -- github: KatolaZ ] signature.asc Description: PGP signature ___ Dng mailing list Dng@lists.dyne.org https://mailinglists.dyne.org/cgi-bin/mailman/listinfo/dng
Re: [DNG] What should an Install Guide accomplish?
Concise is perfect, if comprehensive, within reason. And, perhaps gilded by a (growing?) collection of links to "user stories"? Ralph. chillfan--- via Dng wrote on 02/01/19 16:53: > Historically the community has always responded to things that are minimal > and simple, and not so much to things that are bloated or windowsy, or > similar. Imho, a reason why a new user might look to Devuan could be because > it's less like windows than some of the others, and the community supports > the goal of simpler living with your OS. > > Actually, I think these problems should be solved just not directly in > Devuan. If there comes a time when someone creates a spin specifically for > new users, that would solve all those problems. > > Cheers, > > chillfan > > ‐‐‐ Original Message ‐‐‐ > On Tuesday, January 1, 2019 11:34 PM, Michael > wrote: > >> Hi golinux and everyone else, >> > >> Okay, I’m breaking this topic off from the ‘Added desktop-live to the install >> guides’ as it seems we have a much higher, philosophical level decision to >> make before we can continue with editing the Devuan Install Guide. Which is: >> > >> == What should an Install Guide accomplish? >> > >> # >> > >> == >> > >> My take is that an Install Guide is a complete set of instructions that a >> person can follow to fully accomplish the task. There are no ambiguities >> presented to the user, as it is literally do step a), do step b), do step >> c) ... >> > >> Each step should be fully explained and if there is more than one primary >> method of doing any of the steps, then each method is explained. In this >> case my take is that both Nix and Windows instructions should be available. >> > >> # Minor points >> > >> === >> > >> = I am fully against against repeating any information on a website. As doing >> so almost always leads to discrepancies between the difference sources. If >> the Devuan site is using a CMS of some sort, then a single source should be >> able to be created and block inclusions can be then placed anywhere else on >> the site as needed. [1] >> > >> = I do think that anything a user needs to know to make an intelligent >> decision should be either on the page or directly linked to. If linked to, >> then clicking the link should not close or overwrite the Install Guide page. >> > >> = 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. >> > >> = If golinux agrees to ‘an over abundance of information approach,’ I have no >> issue re-writing the whole guide. (As you may have noticed I’m a bit gabby.) >> I will need someone with a Windows box to QC those instructions. >> > >> # >> > >> == >> > >> Okay, that’s my fairly opinionated opinion. I think ultimately this is >> golinux’s decision, but please everyone else jump in with yea’s, nay’s, and >> what you think the answer to the question is ;) Also, please don’t feel shy >> about bringing up what you think the ramifications might be for the different >> options/opinions/methods. I bring this last point up, as I have a gut feel >> that if we come to agreement on the ramifications, then we’ll have >> our ‘decision’ per say made for us. >> > >> Best Regards All and Happy New Year!, >> Michael >> > >> PS: golinux, my full apologies if I’ve stepped on your toes :( and/or >> exceeded what you’re willing to take under discussion. >> > >> [1] I host and manage Drupal (CMS) websites, this generally takes 10 minutes >> to setup. I can discuss this offline with whoever as desired. >> > >> Dng mailing list >> Dng@lists.dyne.org >> https://mailinglists.dyne.org/cgi-bin/mailman/listinfo/dng > > > > ___ > Dng mailing list > Dng@lists.dyne.org > https://mailinglists.dyne.org/cgi-bin/mailman/listinfo/dng > ___ Dng mailing list Dng@lists.dyne.org https://mailinglists.dyne.org/cgi-bin/mailman/listinfo/dng
Re: [DNG] What should an Install Guide accomplish?
Historically the community has always responded to things that are minimal and simple, and not so much to things that are bloated or windowsy, or similar. Imho, a reason why a new user might look to Devuan could be because it's less like windows than some of the others, and the community supports the goal of simpler living with your OS. Actually, I think these problems should be solved just not directly in Devuan. If there comes a time when someone creates a spin specifically for new users, that would solve all those problems. Cheers, chillfan ‐‐‐ Original Message ‐‐‐ On Tuesday, January 1, 2019 11:34 PM, Michael wrote: > Hi golinux and everyone else, > > Okay, I’m breaking this topic off from the ‘Added desktop-live to the install > guides’ as it seems we have a much higher, philosophical level decision to > make before we can continue with editing the Devuan Install Guide. Which is: > > == What should an Install Guide accomplish? > > # > > == > > My take is that an Install Guide is a complete set of instructions that a > person can follow to fully accomplish the task. There are no ambiguities > presented to the user, as it is literally do step a), do step b), do step > c) ... > > Each step should be fully explained and if there is more than one primary > method of doing any of the steps, then each method is explained. In this > case my take is that both Nix and Windows instructions should be available. > > # Minor points > > === > > = I am fully against against repeating any information on a website. As doing > so almost always leads to discrepancies between the difference sources. If > the Devuan site is using a CMS of some sort, then a single source should be > able to be created and block inclusions can be then placed anywhere else on > the site as needed. [1] > > = I do think that anything a user needs to know to make an intelligent > decision should be either on the page or directly linked to. If linked to, > then clicking the link should not close or overwrite the Install Guide page. > > = 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. > > = If golinux agrees to ‘an over abundance of information approach,’ I have no > issue re-writing the whole guide. (As you may have noticed I’m a bit gabby.) > I will need someone with a Windows box to QC those instructions. > > # > > == > > Okay, that’s my fairly opinionated opinion. I think ultimately this is > golinux’s decision, but please everyone else jump in with yea’s, nay’s, and > what you think the answer to the question is ;) Also, please don’t feel shy > about bringing up what you think the ramifications might be for the different > options/opinions/methods. I bring this last point up, as I have a gut feel > that if we come to agreement on the ramifications, then we’ll have > our ‘decision’ per say made for us. > > Best Regards All and Happy New Year!, > Michael > > PS: golinux, my full apologies if I’ve stepped on your toes :( and/or > exceeded what you’re willing to take under discussion. > > [1] I host and manage Drupal (CMS) websites, this generally takes 10 minutes > to setup. I can discuss this offline with whoever as desired. > > Dng mailing list > Dng@lists.dyne.org > https://mailinglists.dyne.org/cgi-bin/mailman/listinfo/dng publickey - chillfan@protonmail.com - 0xB179B25B.asc Description: application/pgp-keys signature.asc Description: OpenPGP digital signature ___ Dng mailing list Dng@lists.dyne.org https://mailinglists.dyne.org/cgi-bin/mailman/listinfo/dng
Re: [DNG] What should an Install Guide accomplish?
On Tue, 1 Jan 2019 17:34:57 -0600 Michael 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
[DNG] What should an Install Guide accomplish?
Hi golinux and everyone else, Okay, I’m breaking this topic off from the ‘Added desktop-live to the install guides’ as it seems we have a much higher, philosophical level decision to make before we can continue with editing the Devuan Install Guide. Which is: == What should an Install Guide accomplish? # # # My take is that an Install Guide is a complete set of instructions that a person can follow to fully accomplish the task. There are no ambiguities presented to the user, as it is literally do step a), do step b), do step c) ... Each step should be fully explained and if there is more than one primary method of doing any of the steps, then each method is explained. In this case my take is that both Nix and Windows instructions should be available. # # Minor points = I am fully against against repeating any information on a website. As doing so almost always leads to discrepancies between the difference sources. If the Devuan site is using a CMS of some sort, then a single source should be able to be created and block inclusions can be then placed anywhere else on the site as needed. [1] = I do think that anything a user needs to know to make an intelligent decision should be either on the page or directly linked to. If linked to, then clicking the link should not close or overwrite the Install Guide page. = 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. = If golinux agrees to ‘an over abundance of information approach,’ I have no issue re-writing the whole guide. (As you may have noticed I’m a bit gabby.) I will need someone with a Windows box to QC those instructions. # # # Okay, that’s my fairly opinionated opinion. I think ultimately this is golinux’s decision, but please everyone else jump in with yea’s, nay’s, and what you think the answer to the question is ;) Also, please don’t feel shy about bringing up what you think the ramifications might be for the different options/opinions/methods. I bring this last point up, as I have a gut feel that if we come to agreement on the ramifications, then we’ll have our ‘decision’ per say made for us. Best Regards All and Happy New Year!, Michael PS: golinux, my full apologies if I’ve stepped on your toes :( and/or exceeded what you’re willing to take under discussion. [1] I host and manage Drupal (CMS) websites, this generally takes 10 minutes to setup. I can discuss this offline with whoever as desired. ___ Dng mailing list Dng@lists.dyne.org https://mailinglists.dyne.org/cgi-bin/mailman/listinfo/dng
