On 02/08/11 15:45, Mihai Popescu wrote: ... > I will send here another thing. I hope it will be received nicely. I > mean I don't know how to tell it to be nice for everyone. But I will > tell it: parts of FAQ go into being more difficult and more abstract > than the style it use to be back in time. This is how I feel it. Maybe > the author was changed , I don't know.
well, it's been me since 2002... Of course, I inherited some darned good content that was there, stuff that got me going further with OpenBSD in three days than I got with years of poking at Linux. As you provide no hard details, I'm receiving it neutrally, at best. But hey. The problem any teacher of groups or writer has is they will bore some and lose others. We aren't gonna get the point through to all students or readers, at least not on the first pass. It's a balancing trick -- include all the detail one might want to, you will lose your readers. Include too little, they are left with questions. IF you want to cite cases of "This article was better back in CVS revision 1.54 than it is now" and detail why you feel that was the case, I'm more than happy to listen (it is rather cool that CVS holds all revisions of the website going back to near the beginning of the OpenBSD project, and the web interface makes it easy to view them directly!). However, I believe people are more likely to complain than to praise, and you are really the first I recall making this kind of statement, I think I'm doing not too badly. :) That doesn't mean, of course, that I can't do better. > This is now: > "4.13.7 - I got an SHA256 mismatch during install! > Checksums are embedded in the install kernels for the file sets that > are used for the system install. > > Actual -release file sets should all match their stored checksums. > > At times, snapshots may not have proper checksums stored with the > install kernels. This will happen for various reasons on the building > side, and is not reason to panic for development snapshots. If you are > concerned about this, wait for the next snapshot." > > OK, reading this, what to do next? If I will be concerned, i will > wait. But why I should be concerned ? If I'm not concerned, can I > install with wrong checksum? ... I would hope that would be obvious from the "is not reason to panic" and "if you are concerned about this...", the implication would be that if you aren't concerned, carry on. But obviously, something didn't go as planned, so I'd suggest you think about it before blindly reacting one way or another. This is also a perfect case of if I start going into detail about why the checksums may not match, I'm going to bore a lot of people who will intuitively understand the building and distribution process, others won't care, and all will be hit with a lot of "difficult and abstract" words they could live without (though "simple, concrete, but way too many!" would be a better description). I made it short and sweet and you don't like it. Hey, I hit some people dead on, I miss a few. I missed you. I wish I was a perfect enough teacher that I COULD avoid boring the brilliant and still not miss the slow, but I'm not, no teacher or writer I've met is, and I'm not going to lose any sleep over it. I do recognize I may drift into Americanisms (and occasional Nick-isms) that may not "travel" well, always feel free to point those out to me. The FAQ is written in a fairly "conversational" style, and unfortunately, I'm hopelessly monolingual, so I do sometimes wonder how some of the stuff I write sounds to non-native English (or American, or Nick-ish) speakers and readers. I'm guessing this may be part of your difficulty. > And thing get interesting. I like the "howto" style of documentation. and as long as I'm maintaining the FAQ, you will not see it here. I hate the "just type this and don't ask any questions" style of "HOWTO", and I hate the corruption of the language the non-word "HOWTO" has created, such as: "How to install...?" -- question mark should not be there! It is my belief that things run better for people when they understand the WHYs of what they are doing. It is also my belief that most people can understand the "whys" better than they do, often better than they ever imagined they could. It is my goal to give you the opportunity. I've been told I succeed from time to time. :) Nick.
