SOLVED TrueNAS 12 docs in awful condition compared to 11.3 - can't IX do something?

[morganL]

In light of the current state I'd like to check an explicit aspect, and I hope the reply will be not just positive, but reliable and held to, whatever it may be.

Are you saying in effect, "trust us, we will get the depth and comprehensiveness back, as they used to be, even if in a different format, during the coming year"?

If that's actually what you mean then immediately, I can live with that. Blips happen and a 6-9 month docs blip because resources is livable. Destruction of docs that used to eezist and dumbing down, without equivalent replacement, would be a problem and that's what this has felt like as a slippery slope.

Thanks Stilez, I can confirm that the intent of the 12.0 docs is to be get back to depth and comprehensiveness.... as well as ensuring integrity/accuracy. If information is missing in March, it should be treated as a bug.

Where we do have challenges is making sure any type of reader is happy with the docs for their specific use-case. We'd like to improve this over time.... but get completeness and integrity solved first. Sometime complete docs are difficult for a new user to read and navigate and we'll have to provide simpler versions.

 

[Stilez]

Thanks Stilez, I can confirm that the intent of the 12.0 docs is to be get back to depth and comprehensiveness.... as well as ensuring integrity/accuracy. If information is missing in March, it should be treated as a bug.

Where we do have challenges is making sure any type of reader is happy with the docs for their specific use-case. We'd like to improve this over time.... but get completeness and integrity solved first. Sometime complete docs are difficult for a new user to read and navigate and we'll have to provide simpler versions.

@ornias, @Constantin , @danb35, and anyone else who's expressed a concern - what say you? Does this resolve it? It seems to, for me?

If this is okay, then the other question is - are there important lessons/takeaways about communication we should draw, or ask IX to take away? Did we or IXStaff miss chances to reach this point earlier? How could that inefficiency and upset have been avoided/reduced?

Perhaps better explanation and bringing the community with them, better and earlier, when such a big change was considered? Or how? That 6 month docs gap is not trivial, and was worth concern.

Perhaps seeing users as being people with "skin in the game" with ideas worth listening to, not just to be told minimally and after the fact that this or that major thing will change? We aren't all luddites who dislike any change - and we may well have valid concerns and areas of mitigation, that IX hasn't seen as being as important as they are.

I feel that one thing I'd like IX to take from this is, consider seriously introducing a policy of raising anything thats a major change liable to cause apprehension if mishandled, on the forum, in good time, as a policy, and ensure its at least explained as equals and the thinking discussed, and concerns or input or mitigations heeded. Imagine if we'd had a chance to give input and just have the idea of keeping the "one doc" version going 6 months longer, till the hub was effective as mitigation, and the sharing of what Morgan said in his last post above. That would have been easy enough, and if IX were too resource limited to do that, we here could have appreciated the dilemma sooner, maybe found ways to help. How all this could have been avoided. What might be avoided in future.....?

Takeaway thought, for the team.

I have one other question. A number of replies comment as to an IX wiki, and its unreliability, being said to be created and killed several times, so that users don't wish to contribute that way, or are sceptical of its value/durability. While we are sorting things out, what's actually gone on there and what is needed so users can freely input docs and info, and its *not* lost again? Why, actually, github and not a wiki? (Wiki's can support a module that only releases changes to view when they have been approved, for certain categories or criteria of users, if that's an issue.)

I'd really like comments on this please @morganL, if possible? It does seem a valid well tried approach, and I'm not sure whats gone on that others are referring to, or whats causing divergent views on it?

 

[ornias]

@ornias, @Constantin , @danb35, and anyone else who's expressed a concern - what say you? Does this resolve it? It seems to, for me?

Morgan is a great manager, because he just promised (next to) nothing more than he did earlier... ^-^

Information missing after march as a bug is a nice addon, but it isn't the information missing that's worrying me on these docks. One could make a book explaining everything and structure it in such a way that it's not pleasant to use. So no: This doesn't do it for me personally.

I also still miss how UX testing and Market acceptance testing has been done.
Taking responsibility, also means explaining how you are going to prevent the same mistakes in the future.

I'd really like comments on this please @morganL, if possible? It does seem a valid well tried approach, and I'm not sure whats gone on that others are referring to, or whats causing divergent views on it?

I think morgan skipped over the github part, because it is actually very clear for people working on code:
A lot of big projects are slowly moving away from Wiki's, to a Github Backed wiki website. Because it way nicer for workflow reasons for the people that actually need to document their work.

A legacy wiki system is nice for random people sharing random knowhow, a github backed wiki system is nicer if there is a core user-group that also uses github to write the code itself.

 

[Stilez]

Morgan is a great manager, because he just promised (next to) nothing more than he did earlier... ^-^

Information missing after march as a bug is a nice addon, but it isn't the information missing that's worrying me on these docks. One could make a book explaining everything and structure it in such a way that it's not pleasant to use. So no: This doesn't do it for me personally.

I also still miss how UX testing and Market acceptance testing has been done.
Taking responsibility, also means explaining how you are going to prevent the same mistakes in the future.

I read into his post, close to a promise that it's a genuine intent for get the docs back to historical par, and not in years but within a few months, with anything omitted being considered a bug or exception to be noted for fixing. Maybe thats giving benefit of doubt, or I'm not cynical enough ;-) but I think it's genuine and hope it works that way - if not I would be one hurt disappointed user, and would remind Morgan of this thread. But I'm happy to suspend how I feel on the back of what seems a promise it's now a focus to be brought to speed rapidly and fully. He's been open about trhe docs team, and how IX has worked it, which was not covered so informatively before. I don't (currently) see reason to doubt, if he can deliver the intent.

@morganL - if I'm wrong in any way to so take it, please tell me now. I don't just want to have it gradually dawn on me after a whole new thread in a few months time.

I think morgan skipped over the github part, because it is actually very clear for people working on code:
A lot of big projects are slowly moving away from Wiki's, to a Github Backed wiki website. Because it way nicer for workflow reasons for the people that actually need to document their work.

A legacy wiki system is nice for random people sharing random knowhow, a github backed wiki system is nicer if there is a core user-group that also uses github to write the code itself.

Not being on that side of things, that's informative - thank you.

 

[Stilez]

@morganL and @ornias (since you discussed coding the docs before) - one other thing for completeness and usability:

If the docs hub does get up to speed, we *do* IMO need a version capable of offline use, however crudely arranged. Will it be possible to figure some code that, when the hub updates and a PR is committed, auto-builds an updated ZIP of the hub, and single file PDF version, to match? And the ability of TrueNAS to check for, download and update a local "latest copy" of the docs on demand or when the guide is opened.

So that anyone who wants, can view the same information, albeit less navigable, but at least up to date offline?

For IX understanding, this is *not* about a harking back to old ways. If the hub works I'd use it. Its more, there is genuine need of offline, and a bunch of 200 docs is much harder to navigate offline than one PDF, so both formats have value. Once coded it shouldnt need maintaining, so it's not a big burden. But would be important for quality.

I think that would make a HUGE difference, Morgan - one you might underestimate. A lot of comfort and helpfulness, and not huge work. Can that be in the to-do list for hub coding?

 

[ornias]

Yes, offline export is truely needed.
In a nice and structured way, that is.

 

[danb35]

I read into his post, close to a promise that it's a genuine intent for get the docs back to historical par, and not in years but within a few months

"Promise that it's a genuine intent" isn't much of a promise.

 

[danb35]

Sometime complete docs are difficult for a new user to read and navigate and we'll have to provide simpler versions.

Respectfully, I think you have this backward. Some people will just never RTFM; I don't know that there's a good way to deal with that. But the complete docs are essential, they really should come from iX (who is by far in the best position to prepare them), and they should have been there before 12 was released--as you say, it's full of new features, so they need to be documented. And you (collectively) know what's been changed and how--we (the users) know only because we stumble over it, and work out by trial and error how it works.

The "how-to" guides are much easier for the community to prepare. Once we have the complete docs (comprehensive documentation of every bell, whistle, and knob in the system), we can document "how to do X" much more effectively. Uncle Fester's Guide is just one such example; there are many others in the Resources area and elsewhere. If iX wants to provide this also, great, but that's a gap the community can fill (and we have been, for ten years or more).

Thanks Stilez, I can confirm that the intent of the 12.0 docs is to be get back to depth and comprehensiveness.... as well as ensuring integrity/accuracy. If information is missing in March, it should be treated as a bug.

Just to be clear--do @Stilez and I correctly understand that by 1 March, we can expect comprehensive, up-to-date TN12 docs, on par with what's there for 11.3?

 

[Constantin]

@ornias, @Constantin , @danb35, and anyone else who's expressed a concern - what say you? Does this resolve it? It seems to, for me?

Despite having used FreeNAS for the better part of 5 years I still consider myself an utter beginner compared to the demi-gods that roam the halls here. Every time I start to branch down a new FreeNAS feature hallway (VMs, ACLs, whatever), I rediscover my ignorance re: all the details that make up FreeNAS. While mostly complete, the current the "Brockhaus"-style 11.3 encyclopedic documentation is filled with hard facts but it frequently doesn't show the process of putting that information to work.

Hence, I fall back on the forum to ask for help for critical implementation details that I don't really consider that uncommon for someone trying to do something allegedly supported by FreeNAS/TrueNAS. Let's take VMs as an example, i.e. how to make a extra hard drive show up in a Windows VM, how to adjust tuneables to allow for more than 2 cores being allocated to the VM, etc. I found @Yorick's Youtube guide to installing a Windows 10 VM to be a great guide.

Hence, I have been advocating for two sets of information: A continuation of the encyclopedia as seen in 11.3.x as a reference to fall back on to explain terms used in document tree #2, which is the how-to guide that IXsystems seem to be developing for 12.x. I suggest these two document trees grow in parallel, with links peppered throughout the how-to 12.x documentation back to the encyclopedia. Pepper those 12.x how-to guides with plenty of hyperlinks and hopefully, this will give the team the opportunity to develop clean-looking documents yet cover details in-depth for power users.

That approach not only allows the re-use of 80%+ of the information already invested in the current encyclopedia but it also allows the documentation teams to generate really relevant guides on common topics. I'd break them up into bigger sections - for example, one whole site / document dedicated to educating users about use case, pool layouts, what components to select for each use case and why before buying hardware.

People are not coming TrueNAS for the fastest I/O experience (a dedicated hardware RAID will likely give that to you) they are coming for battle-hardened, proven data integrity. So let's make pre-deployment planning as comprehensive as possible so the resultant experience is as pleasant as it should be. Yes, this is something the specialists in the technical sales department at IXsystems do every day, but if you want that to scale, you need a better document. Not everyone has the time, budget, etc. to interact extensively with the sales team. Plus, at the entry level, there are few choices.

Similarly, go into the details of various protocols ahead of time so the so-to-be admin can benefit from the aggregated knowledge here re: hardware, software configuration, etc. before standing up a server. There is a lot of information to mine in the forum and in the various resources that the user base has put together. Again, focus on use cases (ex. how how someone with a lot of VMs might benefit from dedups, special hardware, etc. to make FreeNAS sing).

The next section should be a how to guide for a simple initial setup to allow the user to verify their hardware (i.e. cover burn-in, etc. which really should be a GUI feature IMO), add users, set up a simple share, etc. Then have separate pages dedicated to each protocol. How to set up a VM in detail, for common platforms (Windows, Linux, etc.). Similarly, the various jail experiences could be documented a lot better.

 

[Stilez]

"Promise that it's a genuine intent" isn't much of a promise.

I'm not that cynical today ;-)
I'm not sure how else one phrases it honestly, when any intent *could* be delayed or upended if something unplanned and unscheduled comes along and bites hard.

 

[Stilez]

Despite having used FreeNAS for the better part of 5 years I still consider myself an utter beginner compared to the demi-gods that roam the halls here. Every time I start to branch down a new FreeNAS feature hallway (VMs, ACLs, whatever), I rediscover my ignorance re: all the details that make up FreeNAS. While mostly complete, the current the "Brockhaus"-style 11.3 encyclopedic documentation is filled with hard facts but it frequently doesn't show the process of putting that information to work.

Hence, I fall back on the forum to ask for help for critical implementation details that I don't really consider that uncommon for someone trying to do something allegedly supported by FreeNAS/TrueNAS. Let's take VMs as an example, i.e. how to make a extra hard drive show up in a Windows VM, how to adjust tuneables to allow for more than 2 cores being allocated to the VM, etc. I found @Yorick's Youtube guide to installing a Windows 10 VM to be a great guide.

Hence, I have been advocating for two sets of information: A continuation of the encyclopedia as seen in 11.3.x as a reference to fall back on to explain terms used in document tree #2, which is the how-to guide that IXsystems seem to be developing for 12.x. I suggest these two document trees grow in parallel, with links peppered throughout the how-to 12.x documentation back to the encyclopedia. Pepper those 12.x how-to guides with plenty of hyperlinks and hopefully, this will give the team the opportunity to develop clean-looking documents yet cover details in-depth for power users.

That approach not only allows the re-use of 80%+ of the information already invested in the current encyclopedia but it also allows the documentation teams to generate really relevant guides on common topics. I'd break them up into bigger sections - for example, one whole site / document dedicated to educating users about use case, pool layouts, what components to select for each use case and why before buying hardware.

People are not coming TrueNAS for the fastest I/O experience (a dedicated hardware RAID will likely give that to you) they are coming for battle-hardened, proven data integrity. So let's make pre-deployment planning as comprehensive as possible so the resultant experience is as pleasant as it should be. Yes, this is something the specialists in the technical sales department at IXsystems do every day, but if you want that to scale, you need a better document. Not everyone has the time, budget, etc. to interact extensively with the sales team. Plus, at the entry level, there are few choices.

Similarly, go into the details of various protocols ahead of time so the so-to-be admin can benefit from the aggregated knowledge here re: hardware, software configuration, etc. before standing up a server. There is a lot of information to mine in the forum and in the various resources that the user base has put together. Again, focus on use cases (ex. how how someone with a lot of VMs might benefit from dedups, special hardware, etc. to make FreeNAS sing).

The next section should be a how to guide for a simple initial setup to allow the user to verify their hardware (i.e. cover burn-in, etc. which really should be a GUI feature IMO), add users, set up a simple share, etc. Then have separate pages dedicated to each protocol. How to set up a VM in detail, for common platforms (Windows, Linux, etc.). Similarly, the various jail experiences could be documented a lot better.

I think they can be combined effectively, and also solve the breadth vs. entry count vs. depth issue of the sidebar menu. But I'd like IX consent to dick round with their github to show how, if possible, before diving in and wasting my own time ;-)

 

[morganL]

Stilez said:
I have one other question. A number of replies comment as to an IX wiki, and its unreliability, being said to be created and killed several times, so that users don't wish to contribute that way, or are sceptical of its value/durability. While we are sorting things out, what's actually gone on there and what is needed so users can freely input docs and info, and its *not* lost again? Why, actually, github and not a wiki? (Wiki's can support a module that only releases changes to view when they have been approved, for certain categories or criteria of users, if that's an issue.)

I'd really like comments on this please @morganL, if possible? It does seem a valid well tried approach, and I'm not sure whats gone on that others are referring to, or whats causing divergent views on it?

As @ornias indicated, Github (and Gitlab) is the preferred tool of for our engineering team. We think it provides good version control, collaboration tools and metrics.

As for retaining content, yes there was an issue with a wiki about 4 years ago. Since then we've been using these forum pages and the Resources section for user contributed content. There has been no data loss that I'm aware of.

The new documentation system also allows for user contributions, but it does not replace the resources pages. My summary would be:

Resources pages allows a user to own and maintain specific content as well as have a conversation about it.​

​

Documentation pages can be user contributed but will be subject to editing and changes over time. These pages will get more views and use.​

Open Source projects work because there is a community. Some people contribute to specific communities and use others. Some people just use the resources and provide feedback. There is no requirement to contribute, but all contributions are welcome and appreciated.

iXsystems pay for many professionals to be part of the TrueNAS team.... they contribute greatly to the Community, but we also need to ensure they are engaged on commercial projects and products so than can afford to pay them and keep growing the project and team. Everyone benefits from this, but we do have to decide where to allocate resources and how to make sure we are efficient. There is no free lunch... even if there is free NAS software!

Happy New year to everybody..... let's all hope 2021 is much better than 2020 has been.

 

[danb35]

While we are sorting things out, what's actually gone on there and what is needed so users can freely input docs and info, and its *not* lost again?

Of course, just because iX isn't providing one, doesn't mean there can't be a wiki--that's where Fester's Guide is hosted...

 

[Basil Hendroff]

iXsystems pay for many professionals to be part of the TrueNAS team.... they contribute greatly to the Community, but we also need to ensure they are engaged on commercial projects and products so than can afford to pay them and keep growing the project and team. Everyone benefits from this, but we do have to decide where to allocate resources and how to make sure we are efficient. There is no free lunch... even if there is free NAS software!

I think I'm confident in suggesting that your paying customers would expect full documentation.

Why are we even debating complete docs vs how-to docs? I don't think it's a case of one or the other. There's certainly a place for both, but if there's a choice of only one, a complete reference wins hands down every time for me.

 

[danb35]

Open Source projects work because there is a community.

TrueNAS is not a "typical" community-supported open source project. It's a corporate-provided, commercial product, that happens to be made with open source software and (for the most part, barring the enterprise features) freely released. The community has virtually zero say over the software itself (sure, there's the silly voting system in Jira, but the most that gets us is, "if it gets enough votes, we'll think about it"). PRs on GitHub are ignored. This is your (plural, throughout this post) product, what's in it is what you want in it, it's largely there because that's what you believe you can sell to your customers, and we have no control over any of that. This accounts for some of the otherwise-baffling decisions in the feature set (e.g., why only support AWS Route53 for ACME validation? Because you knew you were doing "TrueNAS in the cloud" on AWS, so you needed that--and only that--DNS support).

So you have your commercial product, most of which you release for free. There's a good business reason to do that, of course; it gives you a lot more real-world testing than you can possibly do in-house. And certainly we benefit from it, and many of us spend a great deal of time supporting your product. But now it really sounds like you're expecting the community to write the docs for your commercial product for you. Not only is this a sharp departure from your previous practice, it seems both presumptuous and foolhardy to do so. I think "presumptuous" is fairly obvious. As to "foolhardy", are you going to trust whatever we happen to spit out as the docs you're selling to your enterprise customers? If not (and I'd sincerely hope you wouldn't), you're going to need to spend significant time vetting and editing any community contributions. And by that time, I'd wager you've spent more time than it would take to write the docs yourselves.

 

[ornias]

PRs on GitHub are ignored.

Not matter how I agree with most of the community input here. This is definately NOT true.
I've personally, without prior permission/discussion, commited multiple PR's. Varying from simple fixes to an actual feature (ZSTD support) and have always either gotten good feedback or they have actually been merged.

I've also given feedback on PR's by IXsystems developers, which also mostly gets a thorough response. Often byond what I experience with "true" opensource projects. Generally speaking the devs are also very open to discuss their design choices for PR's, although they don't always have the time to do so.

 

[danb35]

Perhaps my experience of a PR sitting untouched for 6+ months is atypical, then. Or your experience might be the exception, though it sounds more extensive than mine.

 

[ornias]

Perhaps my experience of a PR sitting untouched for 6+ months is atypical, then. Or your experience might be the exception, though it sounds more extensive than mine.

I think thats more of a general problem with opensource tbh...
I'm one of the people behind the original ZSTD PR on OpenZFS... and I can tell you, some projects/PR's just aren't that much of a priority and if you happen to be one, you can often expect 2 years or more till someone actually takes a thorough look.

Sometimes priorities are there for a reason, sometimes they are there because someone is an A hole.
But I know for very sure, it's not IX's policy to ignore PR's.

Anyway:
Got a link for your PR?

 

[morganL]

I think I'm confident in suggesting that your paying customers would expect full documentation.

Why are we even debating complete docs vs how-to docs? I don't think it's a case of one or the other. There's certainly a place for both, but if there's a choice of only one, a complete reference wins hands down every time for me.

Basil, Yes, paying customers expect full documentation and get it. Over 99% of them are using 11.3-U5 and earlier. They are generally running business critical apps and are more conservative. We expect a slow transition to start with 12.0-U2 and documentation to be relatively complete by then.

We're not debating complete docs vs how-to-docs.... both are needed, but it is a process and there are limited resources. Anyone that wants to contribute is greatly appreciated. Even writing forum posts about positive and negative experiences greatly helps with the community generated knowledgebase.

 

[morganL]

TrueNAS is not a "typical" community-supported open source project. It's a corporate-provided, commercial product, that happens to be made with open source software and (for the most part, barring the enterprise features) freely released. The community has virtually zero say over the software itself (sure, there's the silly voting system in Jira, but the most that gets us is, "if it gets enough votes, we'll think about it"). PRs on GitHub are ignored. This is your (plural, throughout this post) product, what's in it is what you want in it, it's largely there because that's what you believe you can sell to your customers, and we have no control over any of that. This accounts for some of the otherwise-baffling decisions in the feature set (e.g., why only support AWS Route53 for ACME validation? Because you knew you were doing "TrueNAS in the cloud" on AWS, so you needed that--and only that--DNS support).

So you have your commercial product, most of which you release for free. There's a good business reason to do that, of course; it gives you a lot more real-world testing than you can possibly do in-house. And certainly we benefit from it, and many of us spend a great deal of time supporting your product. But now it really sounds like you're expecting the community to write the docs for your commercial product for you. Not only is this a sharp departure from your previous practice, it seems both presumptuous and foolhardy to do so. I think "presumptuous" is fairly obvious. As to "foolhardy", are you going to trust whatever we happen to spit out as the docs you're selling to your enterprise customers? If not (and I'd sincerely hope you wouldn't), you're going to need to spend significant time vetting and editing any community contributions. And by that time, I'd wager you've spent more time than it would take to write the docs yourselves.

Is the glass half-empty or half-full? It is true this is a company-provided project ( not sure that iXsystems with < 200 people qualifies as a "corporation" in the classic smoke-stack sense) and we have to make decisions based on support of paying customers and generating revenues/incomes to pay employees, BUT there are a lot of side benefits to the community because of that (e.g more developers, QA, documentation - better quality code).

I'll disagree that the Community has "no say".... From my vantage point, I'd estimate that over 30% of new features are community generated ideas. If you include all the OpenZFS feature and work, it might be >50%. It is true that we decide which features to pursue, integrate and test.... and prefer features that will eventually be useful to businesses and enterprises and not put their operations/data at risk. As an example, we chose AWS as a 1st cloud platform because most of our customers have chosen AWS and they do a good job with documenting their APIs and processes. As with CloudSync we can extend this later to other clouds as we see requests. Forum posts and jira tickers are how we learn.

We don't expect the Community to write the docs. We've done >90% ourselves until now and will keep doing it. However, we realize that documentation is never finished and there are always additional notes to add, especially on how and why to do things. For that reason, we want to enable contribution from anyone with knowledge or experience (Including our own developers, QA team, support team, and SEs). We think the documentation will eventually be better.

It could be that editing community contributions takes more effort than writing them. We're optimistic here and assume we'll learn from both the intent of the contribution and the knowledge of the contributors. As we've seen from these forum conversations, there is a lot of technical and communications talent out there. Let's review at the end of 2021.