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

[ornias]

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.

I can attest from that, most of the design of the new Apps backend design for SCALE, is in fact due to community and developer feedback.
For example: Think about how hardware transcoding got a first-row-seat this time.
But also: how implementing custom catalogs is going to be easier by not requiring dozens of repositories.

 

[danb35]

Is the glass half-empty or half-full?

I wasn't attempting to make a value judgment one way or the other--there are pros and cons both ways, I think. Just pointing out that they're different, with different dynamics. Expectations that may be reasonable for a true community project may not be so for a corporate product, and vice versa.

We don't expect the Community to write the docs. We've done >90% ourselves until now and will keep doing it.

We're not debating complete docs vs how-to-docs.... both are needed,

This (both quotes) is good to hear. I'm not sure if this represents a change of position, or if some of us had misunderstood Kris' earlier posts here, but I know neither of these statements is consistent with the impression I'd gotten at that time.

 

[ornias]

I think it's important to get back on topic:

There are a few concerns here:
1. The Docs style being a pain to navigate
2. Missing information on the docs (primarily feature and function descriptions)
3. No classic book style PDF version being available.

@morganL Promised to have all missing information fixed before March, or otherwise it's a bug and not a choice. I think that solves issue 2 or at least we should give them the time to do so and hold IX accountable if they don't. I think we can leave it at that for now at least.

But i've not heard a solid proposal for 1. and 3. yet.

Is IX willing to actually have a UX professional look at 1. and have some acceptence testing done?*
Is IX willing do all willing adaptions needed to be able for administrators to be able to get 3 in their hard-copy folder? and if so, what timeframe can we expect?

* This might already be done, in which case someone should get fired for complete and utter incompetence.
Considering I previously used another curse-reference here and the docs team multiple people felt offended enough to report it, I think we can safely assume this is actually the case.

 

[Stilez]

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.​

​

Then I think a standard way to link from docs to resources, so the good resources get easier to find. For example a "Further Resources: (LIST)" at the bottom of docs pages, where theres a *good* resource or thread relevant to that topic. That would help users a lot. A lot of "whats going on" and more niche" How do I" are in the forum and resource threads, so rather than links scattered, let's have one "further resources" footer style for them. Readers will know they may be less perfect than docs, but wider content.

 

[Stilez]

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.

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've proposed docs and code PRs, and usually they have been accepted or at least taken seriously, so mostly I agree with @ornias .

But... the first time I proposed "improve v12 docs" on Jira, it was tagged "private suggestion" and blocked from public view, the *only* post of mine to be so although nothing private in it at all, and then immediately tagged "WONTFIX" or similar as well. I can only interpret that as "You aren't allowed to say that you have a docs concern, and nobody else is allowed to see that a user expressed a docs concern either." That really bloody stung, @morganL.

I should say, that's the only time that's ever happened to me here. I hope never again.

 

[Stilez]

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.

Let's not wait 12 months to do so. If we can't get a pretty good idea and enough data to back it, by about April or May 2021, something's not right :)

 

[Stilez]

I think it's important to get back on topic:

There are a few concerns here:
1. The Docs style being a pain to navigate
2. Missing information on the docs (primarily feature and function descriptions)
3. No classic book style PDF version being available.

@morganL Promised to have all missing information fixed before March, or otherwise it's a bug and not a choice. I think that solves issue 2 or at least we should give them the time to do so and hold IX accountable if they don't. I think we can leave it at that for now at least.

But i've not heard a solid proposal for 1. and 3. yet.

Is IX willing to actually have a UX professional look at 1. and have some acceptence testing done?*
Is IX willing do all willing adaptions needed to be able for administrators to be able to get 3 in their hard-copy folder? and if so, what timeframe can we expect?

@morganL - this is a good example where closer liaison with the community here, would get a tighter sense of what's good for the product and market.

Why not try an experiment. Open a thread on the forum, for IX to get user input and discussion on two questions @ornias pinpoints:

1. What kind of navigation (and ideally also suggested navigation UI mockup) is needed?
2. How should the hub be made available offline? What format/s, and what code used to create?

The community, especially with IX input and comments from Morgan, should be perfectly able to suggest really good UI and resolve differences between ourselves, and come up with good solid ideas. If we as a group like them, and we answer those bvearing in mind the wide range of customers (neophyte to enterprise), the odds are good IX will have a ready made answer on those 2 points, with almost no staff time and effort.

Let us help. Trust us. Instead of a team meeting and a few hours and one person tasked to do it, and who knows the reactions, let us do it. Or at least give it a try, let us have a first crack at it. We will probably spend more time on it, with more diverse views, and quite likely a more solid outcome.

Could you try that approach, Morgan?

I should add - I have a second motive for asking. If it works, its a model I'd like to ask that IX use us more often. You say "Community can contribute" but you don't really make use of us, then if its not great we have to argue to convince you the person tasked did a bad job, and that the in-house review has accepted a bad job (because at that point you've got skin in the game on backing the tasked outcome good or bad). Let us have a go at some of the issues, where its well defined. It'll show genuine wish to work with us and let us contribute, and who knows, probably deliver better and with fewer resources in some cases. This is a good example to test it on. Please? :)​

​

** @ornias - theres a word you used in the footnote to your post that I think is ugly, may upset some, silently, any chance of an edit? :)​

 

[morganL]

There are a few concerns here:
1. The Docs style being a pain to navigate
2. Missing information on the docs (primarily feature and function descriptions)
3. No classic book style PDF version being available.

@morganL Promised to have all missing information fixed before March, or otherwise it's a bug and not a choice. I think that solves issue 2 or at least we should give them the time to do so and hold IX accountable if they don't. I think we can leave it at that for now at least.

That's a good way of thinking about the issues. The current plan of attack is:

2. Completeness and accuracy "by March".... I don't think I said "before March" but it will certainly improve before March.​

3. Offline pdf version after 2. completeness and accuracy​

1. Improve navigation and UI. after 3. The UI team is currently focussed on improving SCALE UI which will then get re-used in CORE.​

@Stilez There is a reason why I recommended 12 months to evaluate. Currently less than 6% of systems are on 12.0 and less than 1% of customers are there. We expect it will take 12 months to get close to 50% of active users. If the plan goes to schedule, during the 2nd half of 2021, the documentation will be more comprehensive that it has ever been and cover both 12.0 and SCALE.

 

[Stilez]

@Stilez There is a reason why I recommended 12 months to evaluate. Currently less than 6% of systems are on 12.0 and less than 1% of customers are there. We expect it will take 12 months to get close to 50% of active users

I figured you'd be on 60% already. Just wow? :) seems I was wrong?

 

[morganL]

I figured you'd be on 60% already. Just wow? :) seems I was wrong?

Storage is a conservative business. There are many systems that haven't been upgraded for many years.
Forum users are heavily weighted toward the early adopter community..... which gives a different impression.
This might explain our differing views of documentation needs.

 

[ChrisRJ]

I hope it is not too off-topic here, but I wanted to throw in a story as to why the storage business is as "conservative" (=extremely paranoid) as it is. When working for a global IT manufacturer during the early 2000s, a colleague told the story of a SAN system that went belly-up due to an unknown firmware bug, combined with people not strictly following checklists when doing maintenance work.

This system was the central storage platform for a federal state and therefore included all their ERP/finance data, but also everything related to law enforcement. The issue was escalated to the highest technical level and it took about 8 hours to confirm that the system was truly bricked. There was a replacement unit some 1500 km away and in a different country. These things weigh tons, so a special truck (vibrations!) had to be ordered to deliver the new system. The folks basically pulled two all-nighters in a row over the weekend and were able to restore the most critical data. The rest was done over the course of the following weeks.

All in all this went reasonably well, given what the worst-case could have been. But even so it cost hundreds of thousands, plus the impact in confidence and therefore future business. In today's world losing the wrong data basically means that you are out of business. This is especially true for regulated industries, where the inability to produce certain data can lead to immediate closure by the authorities. And we have not even touched upon personal liability (and possibly prison) of top management here. Again, I realize this is a bit off-topic, but hopefully interesting for a few folks.

 

[winnielinnie]

If I may chime in. I think an important quality that the documentation should have is to write for the layperson, without frustrating those who are more technically savvy and familiar with the underlying software (ZFS, FreeBSD, Unix permissions).

Another important quality is to clearly define and differentiate between distinct terms.

An example was the confusion in the GUI and documentation (I believe around FreeNAS 11.1'ish time frame?) where the following terms seemed to be used loosely: Encryption Key and Recovery Key

In some cases, the Recovery Key actually referred to the Encryption Key. And further more, the "Encryption Key" may have been confused by new users as meaning the actual key used to encrypt data: it was only used to access the real Master Key (used to encrypted/decrypt data).

I know it sounds redundant and tedious, but it's important: it helps all users of all backgrounds, without taking anything away from those who are technically savvy.

Even terms like "Share Type" when creating a new dataset is vague. It wasn't until later I discovered it really means whether or not to create an ACL upon creation of the dataset. It doesn't actually permanently set any type of "Share" for the new dataset. In fact, I have datasets created with the "Share Type" Generic, in which I access via SMB Shares. Am I going to prison now? ;)

EDIT: Also, colored text for related terms (or different colors for contrasting terms) makes it much easier to relate in one's mind. At least for someone such as myself who is a visual learner.)

 

[morganL]

To provide some perspective on documentation progress, since this forum thread started in September, there have been over 100 major documentation tasks completed and we have less than 20 to complete for TrueNAS 12.0. Examples of ones still to be completed are:

• VLAN creation
• L2ARC recommendations
• GELI Encryption Migration
• Expand “Fibre Channel” article
• Expanded Replication articles for encrypted push/pull
• Finish porting UI help text into existing articles

 

[dld121]

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.

Having been burned by incomplete documentation, how will you allow the reader to recognize that it has been extended to be more complete?

That's a good way of thinking about the issues. The current plan of attack is:

2. Completeness and accuracy "by March".... I don't think I said "before March" but it will certainly improve before March.​

3. Offline pdf version after 2. completeness and accuracy​

1. Improve navigation and UI. after 3. The UI team is currently focussed on improving SCALE UI which will then get re-used in CORE.​

@Stilez There is a reason why I recommended 12 months to evaluate. Currently less than 6% of systems are on 12.0 and less than 1% of customers are there. We expect it will take 12 months to get close to 50% of active users. If the plan goes to schedule, during the 2nd half of 2021, the documentation will be more comprehensive that it has ever been and cover both 12.0 and SCALE.

If your current release was labeled early release, or beta... I would be a happy 11.3x user...after two false starts on 12.x I am going to have to start over again.
Because there are so many HowTo YouTube videos available, which version allows for the legacy GUI as an option?

 

[Adrian]

The 12.0 release notes state "The legacy web interface has been removed and no longer appears as an option in the login screen."
So 11.2 U8 would appear to be what you want.
The legacy GUI is very different to the current one and iX indicated that it would not be coming back. You will have to stay conservative. Even some home users consider that to be better than being on the bleeding edge.
Edited for typo.

 

[morganL]

Having been burned by incomplete documentation, how will you allow the reader to recognize that it has been extended to be more complete?
If your current release was labeled early release, or beta... I would be a happy 11.3x user...after two false starts on 12.x I am going to have to start over again.
Because there are so many HowTo YouTube videos available, which version allows for the legacy GUI as an option?

Part of the answer is this forum. All issues are freely discussed and answered. We have recommended 11.3-U5 over 12.0 or 12.0-U1 for conservative users. There has been over 100,000 machine years running 11.3 and about 10,000 machine years running 12.0 The quality is catching up, but it's not the same yet. The large Open Source community greatly helps with finding bugs in software and documentation. Right now, the largest issues we have found are third party device drivers. These get fixed, but it takes time and effort to diagnose.

When we announce versions, we try to provide release notes and community posts that indicate status .

The 12.0 plan was documented here: https://www.truenas.com/community/threads/truenas-12-0-schedule.85194/

12.0-U1 was announced here: https://www.truenas.com/community/threads/truenas-12-0-u1-plans.89058/

Each Update is an incremental improvement in maturity, quality and documentation. Thanks to automated QA testing, early adopters and bug reporters, our releases are maturing faster than they traditionally have.

Hope your 12.0 experience did not lose any data.... our primary metric for progressing even to BETA is data retention. However, even then, we need >1000 machine years to be confident. BETA users should always have a backup plan.

 

[dld121]

The 3.0 release notes state "The legacy web interface has been removed and no longer appears as an option in the login screen."
So 11.2 U8 would appear to be what you want.
The legacy GUI is very different to the current one and iX indicated that it would not be coming back. You will have to stay conservative. Even some home users consider that to be better than being on the bleeding edge.

Thank you...that is what I needed. So that is what I will start over with.

 

[Stilez]

To provide some perspective on documentation progress, since this forum thread started in September, there have been over 100 major documentation tasks completed and we have less than 20 to complete for TrueNAS 12.0...

My acid test for this will be pretty simple. I'll go look as a keen user would, for more than bare basics. Stuff like this:

• "I want to set up a NAS. And check if it's worth doing dedup. never mind a blanket yes or no, I'm curious, and want to get an idea how easy or what issues I'd face, and the procedures to follow/controls needed."
  (What to watch out for. Issues. And, if you're sure, then how to know when it could be worth it, what you'll need, and what the compromises will be)
  
  
• "I'm using 10 GbE LAN. Are any extra settings recommended for my NAS?"
  (Yes they are)
  
  
• "So I can remove a top level vdev?"
  (Not always, and be very careful when specifying RAIDZ as well, or disks with different logical/physical sector sizes. Were you also warned about these when your pool was created?)
  
  
• "I want to recreate my pool, to move metadata round, change properties for existing as well as new data, how do I do that?"
  (send/recv and local replication CLI or GUI can be tricky, if this isn't made clear)
  
  
• "Is my PSU okay?"
  (Well, is it? How many HDDS are you hanging off that power connector, and did you consider spinup current or staggered spin?)
  
  
• "Do ACLs make sense?"
  (Traditionally badly explained - sorry!)
  
  
• "Can I understand the controls in iSCSI and pool/dataset creation, and their implications, just from the docs alone?"
  (Should be able to)
  
  
• "What file, path, dataset, snapshot and mountpoint length limits apply, for all things to work smoothly?"
  (Changed in 12 due to 64 bit inode and structs landing)

Examples only of the kinds of things I'd expect for any kind of parity with 11.3. Maybe not every last one or detail, but broadly. That kinda level.

These are kinda basic/core stuff for an enthusiast or small business user actually using the NAS, and the kind of things we dip into the docs for, up to 11.3. They should all be clear from the guide, even if not all users will use them. I'm sure we can debate some of these - this one should be in the forum, that one is advanced users only, and so on. But let's skip that. The point is, these are all questions I'd expect to be able to find answers for, in the docs. They are all the kinds of questions I'd expect to find answers to, in 11.3.

 

[morganL]

• "I want to set up a NAS. And check if it's worth doing dedup. never mind a blanket yes or no, I'm curious, and want to get an idea how easy or what issues I'd face, and the procedures to follow/controls needed."
  (What to watch out for. Issues. And, if you're sure, then how to know when it could be worth it, what you'll need, and what the compromises will be)
  
  
• "I'm using 10 GbE LAN. Are any extra settings recommended for my NAS?"
  (Yes they are)
  
  
• "So I can remove a top level vdev?"
  (Not always, and be very careful when specifying RAIDZ as well, or disks with different logical/physical sector sizes. Were you also warned about these when your pool was created?)
  
  
• "I want to recreate my pool, to move metadata round, change properties for existing as well as new data, how do I do that?"
  (send/recv and local replication CLI or GUI can be tricky, if this isn't made clear)
  
  
• "Is my PSU okay?"
  (Well, is it? How many HDDS are you hanging off that power connector, and did you consider spinup current or staggered spin?)
  
  
• "Do ACLs make sense?"
  (Traditionally badly explained - sorry!)
  
  
• "Can I understand the controls in iSCSI and pool/dataset creation, and their implications, just from the docs alone?"
  (Should be able to)
  
  
• "What file, path, dataset, snapshot and mountpoint length limits apply, for all things to work smoothly?"
  (Changed in 12 due to 64 bit inode and structs landing)

That's a pretty advanced set of questions where the answer is often "it depends" Anyone who can answer more than half of them should contact iXsystems for a job - we need you.

Right now, the focus is on making sure if the answers were in 11.3 docs, they should also be in 12.0 docs. Most of these aren't answered in either, but it's a bug in the docs if it is in 11.3 and is not in 12.0. Please identify the ones in that category. Report them as bugs if you need them fixed.

We currently use these forums for TrueNAS CORE and have a team of System Engineers and Support Engineers to research/answer these questions for TrueNAS Enterprise. It is easier to solve the specific problem than it is to solve the general problem for all situations.

With the new modular docs site, it's easier to add/create an article that covers a specific topic like this, but it does require talent and time. I know our team is working on a more advanced ACLs doc - it's a non trivial project.

 

[jgreco]

Storage is a conservative business. There are many systems that haven't been upgraded for many years.

Well, not only is it a conservative business, but it is also a high availability business. Forum users often think nothing of the disruption and mayhem caused by a reboot, much less what can happen as a result of an upgrade.

When you are using your storage for something like VM SAN storage, you may have hundreds or thousands of virtual machines running on it, and in many environments it would be prohibitively expensive to shut them down and start them up later, so an update of the storage system involves evacuating all the VM's from one NAS to another, a process that could take a day or even a week.

Basically, businesses don't pay tens of thousands of dollars for a quality SAN-grade NAS just to use it for trite stuff like storing their media collection. ;-)