PDF Tutorial with Best Practice Examples? (Tell me why I'm stupid)

[jgreco]

Maybe call in @jgreco too! :D

I'd write 1000 pages of boring.

 

[pirateghost]

@cyberj0ck I think the main disconnect here is a difference of opinion that a thorough guide would encourage participation, knowledge, and a deeper understanding of the mechanisms at work rather than detract from it. As always, there's never a magic bullet. For myself I know that at least a guide that includes some detail of the thought processes involved and examples would assist in my full adoption and dedication to understanding freenas. Perhaps I am in the minority though.

Guides almost never incite people to actually understand what they are doing. They blindly follow a guide based on what they want the end result to be.

 

[jgreco]

Guides almost never incite people to actually understand what they are doing. They blindly follow a guide based on what they want the end result to be.

Which is why my virtualization stickies are written as a high level summary of the issues plaguing virtualization.

It's documentation for people familiar with the technologies but unfamiliar with the gotchas of combining them.

 

[cyberjock]

@cyberj0ck I think the main disconnect here is a difference of opinion that a thorough guide would encourage participation, knowledge, and a deeper understanding of the mechanisms at work rather than detract from it. As always, there's never a magic bullet. For myself I know that at least a guide that includes some detail of the thought processes involved and examples would assist in my full adoption and dedication to understanding freenas. Perhaps I am in the minority though.

Guides almost never incite people to actually understand what they are doing. They blindly follow a guide based on what they want the end result to be.

This... exactly. Guides do NOT and never will help people understand. People will see a guide, immediately say "great, I don't have to learn a damn, thing.. I just have to follow this guide" and off they go. When it fails they post in the forum. This behavior is precisely why users with guides suck. It is also why, in my hypothetical guide, it went off on 100 tangents for something very simple. People in this generation do NOT want to learn the material. They want a guide that tells them how to do exactly what they want. If the guide doesn't do exactly that, they'll ask for it and expect... no demand... that you provide it. They'll also expect you to provide it RIGHT NOW and for free. Oh wait. I already said that if a book was written it would be pirated. Gee, back to my original discussion...

Whoops.

Those of us that are interested in learning material are in the minority. By a long shot. More than 75% of users that show up here don't want to learn, they don't give a crap how the stuff works behind the WebGUI. They want an OS that is free, uses old crappy hardware, is 100% reliable, and a file system that is so reliable, secure, and safe that they never have to look at backups for their data ever again.

 

[Bidule0hm]

Yes, exactly that. Personally I don't mind spend hours on reading some docs, wiki articles, etc. (even if I don't need it for a practical application, I just love learning new things) but the current generation is just 95 % assisted sheeps :P

 

[Rilo Ravestein]

Cool. I am a minority :)

 

[Jailer]

Yes, exactly that. Personally I don't mind spend hours on reading some docs, wiki articles, etc. (even if I don't need it for a practical application, I just love learning new things) but the current generation is just 95 % assisted sheeps :p

I'm in the same boat. I love learning new things and actually hate having to ask someone for help. I've always been that way even when I sometimes should ask. I try to only ask for help when I'm really stuck and/or just no matter how hard I try I just can't seem to understand something. Unfortunately as I've grown older the latter seems to occur more frequently. I blame a wasted youth.

 

[jgreco]

I'm in the same boat. I love learning new things and actually hate having to ask someone for help. I've always been that way even when I sometimes should ask. I try to only ask for help when I'm really stuck and/or just no matter how hard I try I just can't seem to understand something. Unfortunately as I've grown older the latter seems to occur more frequently. I blame a wasted youth.

It is a complexity thing. The CPU's I learned to code on, the transistor count was in the low thousands. You could actually understand what every little interaction going on was, toss a logic probe or scope on points, and hack away at the basic structure of the thing if you wanted. Today, there's no hope that you could ever inspect every instruction running on your computer, or be aware of everything at anywhere near that level of detail. The stuff is a lot harder to understand than it used to be.

 

[Bidule0hm]

You can however learn how a simple CPU works and also how some basic bricks of modern CPUs works, then you understand 90% of how a modern CPU works wich isn't bad at all :)

And not all things follow this complexity rise so it's not really a good excuse to not learn how things works...

For those who are interested into learn how a CPU works and how the code is executed on it (ever wondered how a if() is translated at the hardware level for example?) I recommend this website: http://web.cecs.pdx.edu/~harry/Relay/ the explanation paper is here (pdf version here) there is no transistors or other electronic components but only relays, and the paper is very well written, so it's very simple to understand ;)

 

[Luminousdolphin]

Perhaps the word guide is a bit bastardized. Perhaps the stickies, better organized with some visual aids. I don't want hand holding I just want to be sure my time is well spent.

I sense a lot of deep frustration with forum newbies

 

[Rilo Ravestein]

That frustration is mostly because newbies often don't want to spend time learning how things are done. You can explain in detail how something is done, but if you are to lazy to actually learn a bit, if something goes wrong or if you decide to change things, you still can't do it.
If you don't like to learn new stuff, you shouldn't bother with a DIY NAS, especially something sophisticated like FreeNAS

 

[cyberjock]

That frustration is mostly because newbies often don't want to spend time learning how things are done. You can explain in detail how something is done, but if you are to lazy to actually learn a bit, if something goes wrong or if you decide to change things, you still can't do it.
If you don't like to learn new stuff, you shouldn't bother with a DIY NAS, especially something sophisticated like FreeNAS

^ That.

Do you know how many people have messaged me on IRC and in the forums offering me $10-20 to spend 2-4 hours setting up every little thing for them. They don't want to learn anything. They want the answers to make it work. They also want it as cheap as they possibly can.

 

[gpfreitas]

I think a book would be great (and would happily pay $50 for it, even if it's around 200 pages), but I agree that there are too many use cases to cover.

I also think that the FreeNAS Mini, as a product, deserves better documentation.

Putting those two points together: why not focus on the FreeNAS Mini for a book/docs? I could be wrong (and I'm being shamelessly self-serving, as a Mini owner) but I think that it narrows down the use cases: it's a single hardware config, and I expect the people who buy Minis to be somewhat like me: not sysadmin/ZFS/FreeBSD experts, but familiar with the shell and various CLI tools, and certainly not a kid that wants to run FreeNAS on old crappy hardware. There is also the additional benefit of having better support for a paid iXSystems product that will often sell without support anyway.

Another way to simplify things (besides focusing on the Mini) could be to first focus on "what to do to solve a problem" and not on "how to do it in detail". Something like "setup emails for SMART notifications" instead of detailed instructions of how to accomplish that. I think a simple map of "problem" to "recommended solutions" and to "solutions we recommend against", with associated reasoning (and pointers to good sources of information for deeper understanding), can be __very__ useful, easier to write and maintain. And it makes it much easier for one to know what to look for in the docs and forums. But I'm not sure people would be happy with this approach (I would).

As for how to obtain the funding, I think that crowdsourcing may be the way to go. I just don't know if the best way to go is to fund it as a "public good" or not. In the "public good" model, you set the price that it takes to build the thing; once the contributions reach the price, you deliver the product and it becomes available to _everyone_, not only people that contributed. I remember when Travis Oliphant funded "A Guide to NumPy" around 10 years ago successfully following that model or something very similar to that. It worked very well, and a huge community sprung up from NumPy... but it was not clear it would be such a success. Or you could go with the regular "private good" model, a-la Kickstarter.

Cyberjock, if you do decide to go the crowdsourcing path, I would also consider doing it per chapter (or collection of related chapters) instead of a whole monolithic book. Or at least release drafts of chapters as they get written. I would be happy to pay for something smaller, that doesn't cover a lot of stuff, but covers some useful areas well. The "Early Release" by O'Reilly and MEAP series by Manning publications come to mind. Also, I don't know how effective it is, but I __think__ that having one's email printed on one's ebook is a fairly effective piracy deterrent.

A final note about support: I would happily pay for support if it was similarly priced to AppleCare (approx. 200 dollars for 3 years of support, I think). I understand it would not be deep support, but some support at what I consider affordable would be nice.

 

[Redcoat]

I support the "FreeNAS Mini book" suggestion of gpfreitas, being much in the same situation apparently. I found the factory book very unsatisfying. Further, the wizard process did not match the book as the system had been configured and tested already so had an existing volume with data. When I asked iXSystems support about it, responder explained that this was part of the build instructions, so I assume that all purchasers have this experience. I worked my through it but was left uncomfortable despite all my reading here.

 

[gpfreitas]

Thinking about it, I actually would prefer a "public good" model: put a price on each chapter/part of the book and say "it would cost me x dollars to write this chapter". The moment you get a total of x dollars in contributions, write the chapter, then make it available for anyone to download. That way, _if_ the book gets written, we get maximum benefit to everyone. After all, once written, the marginal cost of copying the book is zero.

Any donations above the target could go towards future chapters, or to the writer, or to the FreeBSD foundation, etc.

"But people will just wait and free-ride then!" you may say. Yes, I know :). But maybe not. The key is that free-riding means waiting. If there are enough impatient people that wouldn't mind donating 5-50 bucks to a book that would help them _now_, this might work. So you want to make the book most useful to those impatient (but not cheap!) people, that do not have a lot of time on their hands to become experts in ZFS/networking/security/admin etc. My guess is that FreeNAS mini buyers are precisely that kind of audience.

By the way, does iXsystems have any data on the FreeNAS userbase? Or at least on the FreeNAS mini userbase? I ask because knowing the audience (their skills and time constraints, job and number of dependents or family size being good proxies, I guess) may help target such a book and also because it may help targeting people to write such docs (assuming people would be willing to contribute their expertise in writing, for a price).

Also, does anyone know the pricing / compensation models available in various publishers out there (O'Reilly, Manning, Leanpub, Pragmatic Bookshelf, InformIT, etc.). Do they offer anything along these lines? Anyway, paying an editor could be a "stretch goal"...

As far as keeping the book up-to-date, if one goes with the "public good" model, my suggestion would be to keep it in a public source control repository. GitHub is popular this days, so why not? And FreeNAS docs use reStructured Text... so why not?

 

[cyberjock]

With regards to the data on the FreeNAS userbase, we have some data. Not a lot though. Most Mini owners already know FreeNAS, but want something small that is "more official" for a small business than building on themselves. Some do buy one cold-turkey and learn FreeNAS on the Mini itself.

If I were to crowdsource it, I'd probably do some kind of private-good. Basically the kickstarter would provide enough guaranteed funds to ensure that the book would at least not be a time sink from which there is no financial incentive. For me, the only thing that would really stop me is the time investment for potentially no gain. I just can't convince myself to spend a year of my life to write a book so it can be pirated. :P Unless there is some kind of guarantee that I would make at least some given dollar value before i start, with certain expectations of what I would provide already set, it's a big risk to spend a year of one's life writing a book that might not make any money. Sorry, but spending a year of my personal time to make a book that might only make $5000 isn't a "good deal" in my opinion. I talked to someone who has been involved in book writing, and he told me "Nobody makes any money on technical books. Nobody. People do it because it puts their name on the front page of the book. It gets you invited to conventions to give speeches. Nothing else."

I'm not big on giving speeches. I'm not big on going to lots of conventions. If I wrote it, I'd be doing it for the community. And I think it's only fair that if I make that kind of time commitment to the book that there would be some kind of monetary reward for it.

 

[mjws00]

Seems to me you've hit that nail on the head. Outside of establishing oneself as an expert in the field there isn't much upside initially. However, if one looks at a bit bigger picture the opportunity to speak, and the additional recognition is easy to monetize. Probably to a far greater extent than any kickstarter funded niche book. Especially one about a single SKU.

 

[SilverJS]

I think this would be a fantastic idea. I understand some of the power users' reservations about this, but I think another angle that could be used to look at it (or further develop it) would be to take the existing documentation as a starting point. It's actually not bad at all - I think that, if it was fleshed out a bit with some more scenarios, it would be the 80% solution to what the OP is proposing. By way of examples, I'd like to offer some cases I just recently went through myself, where a more fully fleshed-out documentation set (with examples, I mean) could have helped me and, by the same token, met the OP's intent as I understand it :

- Replication vs RSync. A quick explanation of the underpinnings of both, and how they're usually used by experienced system administrators would have helped me a lot when I went through this twoish weeks ago. (In the end, I chose Replication for the full backup from main to backup box, and I'm still trying to figure out rsync for backups of specific datasets to a third box.);
- Networking. I have to admit I haven't done my full research on this yet (I suspect it's out there in the forums...!...but we're back to OP's point, which is consolidation), but I'm still not sure how best to use the two NIC's on my shiny new SuperMicro board. I'd love nothing more than to pick the brains of experienced power users, to determine what is best for me - and I think this is exactly what OP is going for. So, a couple of scenarios, with implementation examples, would be most helpful to me.

And, I'm sorry, but I'll have to wholeheartedly disagree about gearing this towards the FreeNAS Mini. I'd argue that the vast majority of FreeNAS users are not Mini users. FreeNAS is hardware-agnostic, I realize, but I really do feel that this manual should be about an OS, not a piece of hardware. I do, however, agree with poster's suggestion of having a "Non-Recommended Solutions". Sometimes, just having what NOT to do laid out already makes the job that much easier.

Count me in for funding if required.

 

[Johev]

I would just like to add that with the new requirements, ECC RAM, 8GB RAM minimum, that the user base might be changing. FreeNAS is no longer a cheap system, then nothing worth trusting is. I would buy a book, the only thing that I would want is for it to be current. A book based on version 9.x if 10.x is the current version does not sound appealing to me. ;)

 

[jgreco]

8GB isn't a new requirement. I raised the minimum requirement in the manual about two years ago. FreeNAS, at least in the new version being designed by iXsystems, has never been a "cheap" system.

ECC isn't a new requirement either. ZFS has always required ECC as part of the data integrity protection. You are free to omit ECC, but in return you lose some degree of data integrity protection.