Re: [DNG] Fwd: Re: What should an Install Guide accomplish?
On Sat, Jan 05, 2019 at 10:34:21AM +0100, KatolaZ wrote: > > On the other hand, I personally think that an installation guide > should be a "layered" document: the main thread being the "usual" > install path with only the necessary details, and links to further > information about specific points or possible bifucations. The main > reason is that installation docs serve two (almost antithetic) > purposes: the first one is to allow any newcomer to get a working > system easily. The second one is to provide extensive information to > those who like to understand what is going on under the hood. People > in the first class need just a simple document with figures, people in > the second lot would enjoy extensive explanations and detailed > descriptions. Straightforward main document with links to specific points, bifurcations, and extensive explanations sounds about right. -- hendrik ___ Dng mailing list Dng@lists.dyne.org https://mailinglists.dyne.org/cgi-bin/mailman/listinfo/dng
Re: [DNG] Fwd: Re: What should an Install Guide accomplish?
On Fri, Jan 04, 2019 at 05:07:04PM -0600, Michael wrote: [cut] > > I would not have continued to be a member of this community in light of > golinux’s reply, as I literally can not think of any way to re-word what > he/she wrote into something acceptable. But before I officially unsubscribe, > my ‘agenda’ makes me point out that Devuan 2.0 has a bug with un-mounting > encrypted disks/partitions (FDE) during shutdown which prohibits me from > being able to use Devuan in any event. > Dear Michael, the bug with clean unmount of encrypted root partitions is known, and in not exclusive to Devuan. This is just due to the fact that the script that tries to unmount the root partition waits for it to be unmountable (i.e., when there is no process with open files on /). This is something that cannot be attained, since the root partition is active and used until the end of the boot. You can consult the relevant bug reports at bugs.debian.org, which contain a few more details on the issue. Regarding the documentation thing: I agree that some form of complete Devuan manual would be great. There have been a few efforts in that direction, but it is not even near to completion, so any help would be very welcome. On the other hand, I personally think that an installation guide should be a "layered" document: the main thread being the "usual" install path with only the necessary details, and links to further information about specific points or possible bifucations. The main reason is that installation docs serve two (almost antithetic) purposes: the first one is to allow any newcomer to get a working system easily. The second one is to provide extensive information to those who like to understand what is going on under the hood. People in the first class need just a simple document with figures, people in the second lot would enjoy extensive explanations and detailed descriptions. Unfortunately, it is not easy at all to serve both ends of the GNU/Linux spectrum to the same level of satisfaction. 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] Fwd: Re: What should an Install Guide accomplish?
Quoting Michael (mb_devuan-mailingl...@inet-design.com): [snip quite a lot of quotation whose purpose I'm unclear about] > Dear Devuan Community, /me waves. > I intentionally waited 48+ hours after received this much unexpected > reply by golinux to reply. I first wanted to hear what the Devuan > Community had to reply to the question I put to it on what it wants. > > My ethos is to ‘help.’ I guess you could call that my ‘agenda?’ > Being slapped in the face by golinux’s catch 22 of “because you’ve > asked the community its opinion,” “you don’t understand the community” > doesn’t really lead me to want to ‘help’ the group he/she leads. Dude, you didn't get even very figuratively slapped in the face. Anyway, it's great that you want to help. Personally, I'd suggest, first, install, run, and get to know Devuan. Hang out on the mailing lists and IRC and answer technical questions when you can. Learn Devuan Project's institutions and forums, e.g., make some interesting and useful pages on dev1galaxy. And thus figure out how you can mesh with and help build this community. In anticipation of your doing that, which is not a lot like long lectures on minimalism, giving Devuan volunteers a hard time and chewing up their time, and wanting to be individually briefed on what Devuan desires -- let alone padding your Drupal-deployments portfolio, which the cynic in me strongly suspects this entire noisy campaign is about -- thanks in advance. If you won't do that, oh well -- and please see .signature block. -- Cheers (Drupal sucks ;-> ), A post is just a post Rick Moen My admin will deny. r...@linuxmafia.com The usual disclaimers apply McQ! (4x80)As news spools by. ___ Dng mailing list Dng@lists.dyne.org https://mailinglists.dyne.org/cgi-bin/mailman/listinfo/dng
Re: [DNG] Fwd: Re: What should an Install Guide accomplish?
On Tuesday 01 January 2019 08:11:44 pm goli...@dyne.org wrote: > Sorry. Forgot to send to the list. > > Original Message > Subject: Re: [DNG] What should an Install Guide accomplish? > Date: 2019-01-01 18:50 > From: goli...@dyne.org > To: Michael > > On 2019-01-01 17:34, 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? > > Before that, it might be good for you to understand a little better > where Devuan is coming from. > > > # # # > > > > 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) ... > > As explained elsewhere. These documents were originally created for > inclusion on the ascii isos and have been re-purposed to go on the > website. They were never intended as a complete set of instructions. Are > you even aware of dev1fanboy's wiki? > https://git.devuan.org/dev1fanboy/Upgrade-Install-Devuan > Or the friends of devaun wiki? > https://friendsofdevuan.org/doku.php > > > 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. > > See below. > > > # # 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] > > The site is intricately hand-coded in markdown. Not my doing; I > inherited it and have learned to live with it. > > > = 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. > > The best documemntation will be useless if no one reads it. See below. > Isn't that what a scrollwheel click is for? > > > = 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. > > Even though information is already available on the site and elsewhere, > quite often there will be questions that could be readily answered with > a little effort on the user's part. So it is not a lack of information > problem but a "you can't fix stupid" problem. Bloating the guide won't > change that human behavior. > > > = 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. > > I am a minimalist personally as is the target audience of this distro. > We are not seeking to court desktop users and overtake the desktop > market. In fact, we considered launching this distro without ANY > desktop!! That would have left desktop development to derivatives of > which we have many. So I think you're not understanding who we are, > where we are coming from and where we want to go. > > Feel free to open a project in our gitlab for us to review. > > > # # # > > > > 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. > > It is not MY decision. It is OUR decision. But . . . > > While I can appreciate your enthusiasm, jumping into an established > community that works well together and starting to rearrange the > furniture is a very strange way to make an entrance. Think bull:china > shop. > > > Best Regards All and Happy New Year!, > > Michael > > > > PS: golinux, my full apologies if I’ve stepped on your toes :( and/or > > exceeded what
Re: [DNG] Fwd: Re: What should an Install Guide accomplish?
Quoting chillfan--- via Dng (dng@lists.dyne.org): > I can only agree with that. > > My reservations about doing this are mostly been because of our target > audience, and not wanting to exclude the more savvy users. > > But there's nothing wrong with doing this in a side project that > wouldn't go on the main website. One realises over time that people differ widely in their ways of assessing information. So, ideally, one does iterative usability checking with real (outsider) users, to spot the problems. It's unfortunately rare to have the time and personnel to do so, though. Example from outside of the Devuan context: For many year, I've maintained Web pages for multiple Linux user groups in my area, and among those were the 'directions' pages explaining how to get to meetings via car and various forms of public transit. When I inherited maintenance of Silicon Valley Linux User Group's pages, for example, its directions page was a horribly overlong, ridiculously overcomplicated mess that spent, among other things, two whole paragraphs explaining how to safely cross the light rail tracks. I pruned mercilessly to make the page short and snappy -- but then also pondered _different ways_ to navigate. After a lot of checking, I conceptually divided users of such directions pages into two groups: map people and directions people. Map people (like me) needed a good map plus the street address and cross-street, so I made sure they had those. For the directions people, I made sure there were succinct process descriptions from probably starting points, street by street with turns and distances or block counts, and sometimes 'If you see [X], you've gone too far.' Both groups seemed well enough served after that. But then the world changed after some years, and I realised there was a third, growing group: smartphone addicts -- ones who react irritably if you try to tell them anything beyond street address, i.e., they seem like directions people until they tell you they have absolutely no interest in cross-streets. Of course, they were already provided for by the street address, but could be best served by making the address prominent, e.g., with tags. I hope that's a reasonable example of the 'people assess information in diverse ways' challenge. ___ Dng mailing list Dng@lists.dyne.org https://mailinglists.dyne.org/cgi-bin/mailman/listinfo/dng
Re: [DNG] Fwd: Re: What should an Install Guide accomplish?
I can only agree with that. My reservations about doing this are mostly been because of our target audience, and not wanting to exclude the more savvy users. But there's nothing wrong with doing this in a side project that wouldn't go on the main website. Cheers, chillfan ‐‐‐ Original Message ‐‐‐ On Wednesday, January 2, 2019 2:11 AM, wrote: > > Feel free to open a project in our gitlab for us to review. > 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] Fwd: Re: What should an Install Guide accomplish?
> On Tue, 1 Jan 2019 19:04:32 -0800 > Rick Moen wrote: > > Yes, but in a "how to do it" document (like documentation on a distro's > install procedure), once you've articulated the steps and substeps and > what could go wrong and how to deal with it, you're done. Any requests > for further info, such as theoretical underpinnings, can be done in a > separate document. I always want more information before I start a compilcated procedure, especially if that complicated procedure is mostly automated so that I don't have to attend the details. I always want to understand the theoretical underpinnings. That said, once I do understand, I want a compact exposition of the steps and substeps I have to follow as I follow them. The document I want is such a compact exposition, but with links to the theoretical underpinnings. It drives me crazy not to know what's really going on. -- hendrik ___ Dng mailing list Dng@lists.dyne.org https://mailinglists.dyne.org/cgi-bin/mailman/listinfo/dng
Re: [DNG] Fwd: Re: What should an Install Guide accomplish?
On Wed, 2 Jan 2019 00:18:19 -0500 Steve Litt wrote: > On Tue, 1 Jan 2019 19:04:32 -0800 > Rick Moen wrote: > > > Quoting goli...@dyne.org (goli...@dyne.org): > > > > [much concentrated wisdom] > > > > > The best documemntation will be useless if no one reads it. > > [...] > > > Even though information is already available on the site and > > > elsewhere, quite often there will be questions that could be > > > readily answered with a little effort on the user's part. So it > > > is not a lack of information problem but a "you can't fix stupid" > > > problem. Bloating the guide won't change that human behavior. > > > > Reminds me of a couple of things I've realised through many years > > observing where documentation and user education works and where it > > doesn't -- and pondering why. First of two is this: > > > > http://linuxmafia.com/~rick/lexicon.html#moenslaw-documentation > > > > Moen's Law of Documentation > > > > "The more you write, the less they read." > > Not true, if you structure the writing correctly. Especially now that > we have hyperlinks, it's easy to write good and non-ambiguous docs. > The problem is, people ignore hyperlinks Rowland ___ Dng mailing list Dng@lists.dyne.org https://mailinglists.dyne.org/cgi-bin/mailman/listinfo/dng
Re: [DNG] Fwd: Re: What should an Install Guide accomplish?
Quoting Steve Litt (sl...@troubleshooters.com): > Rick Moen wrote: > > > http://linuxmafia.com/~rick/lexicon.html#moenslaw-documentation > > > > Moen's Law of Documentation > > > > "The more you write, the less they read." > > Not true, if you structure the writing correctly. Especially now that > we have hyperlinks, it's easy to write good and non-ambiguous docs. Well, I've seen the effect I describe at said lexicon item play out in the real world, over and over, with writings from untold numbers of technical people. However, I admire your optimism. Absolutely, I do endorse your notion that part of the problem is reliance on excessively linear prose. As I said, IMO that's a big part of the structural problem with Eric's and my essay. > Yes, but in a "how to do it" document (like documentation on a distro's > install procedure), once you've articulated the steps and substeps and > what could go wrong and how to deal with it, you're done. I _really_ admire your optimism. ;-> > All things being equal, concise is always better than rambling. But man > pages are concise Even the one for GNU find? ;-> ___ Dng mailing list Dng@lists.dyne.org https://mailinglists.dyne.org/cgi-bin/mailman/listinfo/dng
Re: [DNG] Fwd: Re: What should an Install Guide accomplish?
On Tue, 1 Jan 2019 19:04:32 -0800 Rick Moen wrote: > Quoting goli...@dyne.org (goli...@dyne.org): > > [much concentrated wisdom] > > > The best documemntation will be useless if no one reads it. > [...] > > Even though information is already available on the site and > > elsewhere, quite often there will be questions that could be readily > > answered with a little effort on the user's part. So it is not a > > lack of information problem but a "you can't fix stupid" problem. > > Bloating the guide won't change that human behavior. > > Reminds me of a couple of things I've realised through many years > observing where documentation and user education works and where it > doesn't -- and pondering why. First of two is this: > > http://linuxmafia.com/~rick/lexicon.html#moenslaw-documentation > > Moen's Law of Documentation > > "The more you write, the less they read." Not true, if you structure the writing correctly. Especially now that we have hyperlinks, it's easy to write good and non-ambiguous docs. > > Although any piece of writing can be improved, even the best > examples, especially of technical writing, no matter how excellent, > will garner requests for _more detail_ -- far past the point of > reason. Yes, but in a "how to do it" document (like documentation on a distro's install procedure), once you've articulated the steps and substeps and what could go wrong and how to deal with it, you're done. Any requests for further info, such as theoretical underpinnings, can be done in a separate document. > Why? Because, most often, a questioner's immediate reaction > (to not instantly understanding) is to claim that insufficient > information was provided, whether such is true or not. The longer and > more detailed any subsequent, further explanations are, the more > difficulty target readers will have in finding what they need, and > the more they'll demand an even thicker forest of explanations to get > lost in. Not if it's written right. > > Thus, greater conciseness often does _much more good_ than do > longer & more detailed explanations. All things being equal, concise is always better than rambling. But man pages are concise, yet they tend to be of value more as a reminder to those who already know the software than those approaching it for the first time. Anyway, I'm a big believer in giving just enough data so nothing's ambiguous and all terminology is defined. SteveT ___ Dng mailing list Dng@lists.dyne.org https://mailinglists.dyne.org/cgi-bin/mailman/listinfo/dng
Re: [DNG] Fwd: Re: What should an Install Guide accomplish?
Quoting goli...@dyne.org (goli...@dyne.org): [much concentrated wisdom] > The best documemntation will be useless if no one reads it. [...] > Even though information is already available on the site and > elsewhere, quite often there will be questions that could be readily > answered with a little effort on the user's part. So it is not a > lack of information problem but a "you can't fix stupid" problem. > Bloating the guide won't change that human behavior. Reminds me of a couple of things I've realised through many years observing where documentation and user education works and where it doesn't -- and pondering why. First of two is this: http://linuxmafia.com/~rick/lexicon.html#moenslaw-documentation Moen's Law of Documentation "The more you write, the less they read." Although any piece of writing can be improved, even the best examples, especially of technical writing, no matter how excellent, will garner requests for _more detail_ -- far past the point of reason. Why? Because, most often, a questioner's immediate reaction (to not instantly understanding) is to claim that insufficient information was provided, whether such is true or not. The longer and more detailed any subsequent, further explanations are, the more difficulty target readers will have in finding what they need, and the more they'll demand an even thicker forest of explanations to get lost in. Thus, greater conciseness often does _much more good_ than do longer & more detailed explanations. Or, what might be needed is better indexing, or following the classic journalist's inverted pyramid format (http://mtsu32.mtsu.edu:11178/171/pyramid.htm), or the short answer / long answer format I often use -- or just a polite suggestion to Read the Friendly Manual (or Search the Friendly Web). The second: As you may recall, I ended up collaborating wit Eric S. Raymond in co-authoring our essay 'How to Ask Questions the Smart Way' (after we happened to chat circa 2000 and found that we were independently writing the same thing). The end-result has been astonishingly popular (e.g., linked to by a vast number of projects' help pages), and we kept adding additional subtopics readers requested for quite a few years. (IMO, the essay has some damning problems, but that's a different topic.[1]) But Eric was very dismayed that, the more we improved the essay and polished out its most-noted flaws, the dumber people's subsequent objections to it became -- in many cases, suggesting they had completely disregarded what said and attributed to it attitudes and claims that just weren't even remotely present. I pointed out that, no, Eric, you actually have it backwards: Initially, there were a number of reasonable objections to the text. We did a pretty good job fixing those through iterative improvement over quite a few years. Whenever you've satisified all of the reasonable objections, what you're left with are the unreasonable ones, e.g., those who will complain about a text without reading it at all, or read it so poorly as to comprehensively misunderstand it. Eric had fallen prey to a variant of the fallacy of composition (https://en.wikipedia.org/wiki/Fallacy_of_composition), which 'arises when one infers that something is true of the whole from the fact that it is true of some part of the whole'. It's worth remembering that the better suited to task a piece of documentation is, the more head-scratching the remaining complaints will tend to become (not that any documentation can't be improved). [1] Basically, it's too long-winded and too linear. Linear is an artifact of the DocBook toolset. The excessive length is because we kept good-naturedly complying with requests to add things. IMO, what has resulted is an essay very popular with the people who don't need it, e.g., project leaders, but almost totally disregarded by its intended audience. ___ Dng mailing list Dng@lists.dyne.org https://mailinglists.dyne.org/cgi-bin/mailman/listinfo/dng
[DNG] Fwd: Re: What should an Install Guide accomplish?
Sorry. Forgot to send to the list. Original Message Subject: Re: [DNG] What should an Install Guide accomplish? Date: 2019-01-01 18:50 From: goli...@dyne.org To: Michael On 2019-01-01 17:34, 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? Before that, it might be good for you to understand a little better where Devuan is coming from. # # # 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) ... As explained elsewhere. These documents were originally created for inclusion on the ascii isos and have been re-purposed to go on the website. They were never intended as a complete set of instructions. Are you even aware of dev1fanboy's wiki? https://git.devuan.org/dev1fanboy/Upgrade-Install-Devuan Or the friends of devaun wiki? https://friendsofdevuan.org/doku.php 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. See below. # # 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] The site is intricately hand-coded in markdown. Not my doing; I inherited it and have learned to live with it. = 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. The best documemntation will be useless if no one reads it. See below. Isn't that what a scrollwheel click is for? = 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. Even though information is already available on the site and elsewhere, quite often there will be questions that could be readily answered with a little effort on the user's part. So it is not a lack of information problem but a "you can't fix stupid" problem. Bloating the guide won't change that human behavior. = 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. I am a minimalist personally as is the target audience of this distro. We are not seeking to court desktop users and overtake the desktop market. In fact, we considered launching this distro without ANY desktop!! That would have left desktop development to derivatives of which we have many. So I think you're not understanding who we are, where we are coming from and where we want to go. Feel free to open a project in our gitlab for us to review. # # # 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. It is not MY decision. It is OUR decision. But . . . While I can appreciate your enthusiasm, jumping into an established community that works well together and starting to rearrange the furniture is a very strange way to make an entrance. Think bull:china shop. 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. You should be apologizing to the community not to me. We are in this together, have long standing working relationships and have a common vision. It is a big red flag when some stranger who drops in from who knows where and with what agenda starts telling us what to do and how to do it. If you can do it better, s
