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

[ChrisRJ]

[..]
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.

Well, I would rather say these are the things you envision to be of interest, while for me only the ACL topic would be interesting. It is a difficult thing to understand others' needs in a given context, and I have certainly made wrong assumptions in roughly comparable situations. As an example, in the context of my day job I am the main developer for an enterprise-grade configuration management tool. I started this for myself and my demands about 13 years ago and it has grown to more than 10k installations in production world-wide since then. But to this very day I still get surprises as to what features customers will use or ignore. And FreeNAS/TrueNAS probably has a much larger userbase. At the end of the day one needs to prioritize their resources towards paying customers, more or less.

In my opinion I do not see SMB users go for FreeNAS unless either they are also an experienced(!) enthusiast themselves, or if their IT provider handles things. But the typical plumber, barber shop, etc. will most likely go for something like Synology. The latter may be inferior in terms of possibilities and perhaps even capabilities. But it will typically good enough and most non-techie users actual prefer fewer options.

 

[Stilez]

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.

Well, I would rather say these are the things you envision to be of interest. [snip]

In my opinion I do not see SMB users go for FreeNAS unless either they are also an experienced(!) enthusiast themselves, or if their IT provider handles things. But the typical plumber, barber shop, etc. will most likely go for something like Synology. The latter may be inferior in terms of possibilities and perhaps even capabilities. But it will typically good enough and most non-techie users actual prefer fewer options.

Exactly, to you both. The point being, precisely that the guide was of such standard, that even a user who was interested in enthusiast use, had a good chance of finding the answers about using the NAS, in its docs. If it could be done in the GUI, there was an explanation in the docs. I contributed to the docs and I remember the thought that went into making sure they were spot on, by the number of times I was asked to revise a PR until it was acceptable.

Like others have said, you set a good standard in the 11.3 and earlier days.

It's that professionalism in the documentation that these questions are suggesting, as a way to probe. Not that the docs should cover every such detail. But they are examples of the kinds of things one might expect and look for, especially as @ChrisRJ says, the usual TrueNAS user, given fundamental guidance, is perehaps more than typically desirous to try things themself. The docs are that guidance. Not every user will ask such questions, but I picked them as examples of the kind and level of question that different users might expect to find in the docs, when they try to make the NAS do what they want, unlike the usual dumbed down NAS some supply.

(Also, @ChrisRJ - you're only somewhat right. I'd have given example questions about other areas, and tried to, only I don't know enough about many areas of the NAS - VMs, jails, plugins, captive portal - hard to make up questions on areas I've never used. As they were examples only I let it be.)​

 

[Stilez]

While on the topic @morganL:

Since IX bugs and issues moved to Jira, I've filed 91 bugs and suggestions (88 software bugs/suggests, 3 docs).

Precisely 3 of these were quickly marked "security = IX Private" level and blocked from being seen by other community users. No prizes which 3. Every doc post I raised, although not one had any security or adverse implications, and none were spam either (2 x WONT-DO, 1x TO-DO). Compare, not one of my 88 non-docs raised issues, including those marked "WONT-FIX".

(None are "private" - all are either public already, or should be, or are my own created work for copyright purposes)
​

I'm deeply troubled by this, Morgan. I'm not seeing wild conspiracies, but just - this shouldn't happen. It's silly. These aren't (and shouldn't need to be) "private" in any sense, and are in no way sensitive. But marking them such, sends a disturbing message about docs contribution, and practically, may prevent other users seeing or contributing. It makes me wonder what else is not sensitive, but hidden anyway, on the docs side, that I and others might have contributions toward. It makes me feel there's little point contributing to docs issues on Jira.

Can you take a look and either fix (un-secret) or reassure me, while we are in this thread sorting out docs issues handling? I'd appreciate.

Thanks.

 

[morganL]

Precisely 3 of these were quickly marked "security = IX Private" level and blocked from being seen by other community users. No prizes which 3. Every doc post I raised, although not one had any security or adverse implications, and none were spam either (2 x WONT-DO, 1x TO-DO). Compare, not one of my 88 non-docs raised issues, including those marked "WONT-FIX".

Can you take a look and either fix (un-secret) or reassure me, while we are in this thread sorting out docs issues handling? I'd appreciate.

Thanks.

Hi Stilez,

It is just a process issue. Right now, TrueNAS 12.0 documentation has not reached the complete state and so we are not treating documentation issues as standard bugs. Instead, we invited you to the TrueNAS slack community since the docs site is still in its development phase.

The three bugs you reported are part of our general activity and still in development. We don't consider them new requests/issues so we are not treating them as actionable tickets. The tickets we do have are internal discussions and project plans.

In general, we would prefer documentation issues handled via the documentation site via comments and and proposed edits/contributions. It's a more efficient process. The documentation site should be used for minor adds or how to guides or background technology primers.

However, once documentation has reached its "complete" phase, we will be able to handle serious documentation issues as bugs. I'd recommend bugs be reported for issues with the way the documentation site works and major missing and specific sections of information. This should include the user's use-case and the problem caused by the docs.

Cheers

Morgan

 

[Stilez]

Hi Stilez,

It is just a process issue. Right now, TrueNAS 12.0 documentation has not reached the complete state and so we are not treating documentation issues as standard bugs. Instead, we invited you to the TrueNAS slack community since the docs site is still in its development phase.

The three bugs you reported are part of our general activity and still in development. We don't consider them new requests/issues so we are not treating them as actionable tickets. The tickets we do have are internal discussions and project plans.

In general, we would prefer documentation issues handled via the documentation site via comments and and proposed edits/contributions. It's a more efficient process. The documentation site should be used for minor adds or how to guides or background technology primers.

However, once documentation has reached its "complete" phase, we will be able to handle serious documentation issues as bugs. I'd recommend bugs be reported for issues with the way the documentation site works and major missing and specific sections of information. This should include the user's use-case and the problem caused by the docs.

Cheers

Morgan

Thanks. I don't pretend to understand why it means treating them as secret, that just seems inefficient. Even if its a work in progress, its still good for users to see each others bugs and suggestions.

I guess at this point having a response (engagement) matters most and for that, thank you. I'll carry on shoving PRs on the docs github for now, and hope things come together around March-ish.

May we talk on Stack? I have a couple of docs ideas that are easier to discuss that way

 

[MotafokaBR]

Virtualisation is still falky at best on BSD, I don't think thats much of an issue regarding the manual itself.
Although I agree that there should be a LONG LONG list of "know virtualisation bugs" attached.

A list of know bugs would help at least to know if is something wrong in my settings or if I have any "dirty" file or if it is just a known bug and it won't work on my system for now.

 

[MotafokaBR]

That's not been my experience. I have several ubuntu and FreeBSD VMs running with no issues at all.

My Linux VMs run with no issues as well, only Windows VMs that are not good.

 

[Jon Rosebaugh]

And FreeNAS/TrueNAS probably has a much larger userbase. At the end of the day one needs to prioritize their resources towards paying customers, more or less.

With respect, I am a paying customer, having purchased a FreeNAS Mini some years back (and having been recently considering the purchase of a new TrueNAS Mini XL+). Yet I am most familiar with Debian Linux and MacOS, and every time I try to do something even slightly complicated (configuring a jail with dnsmasq for my home network, say) I refer to the docs extensively to make sure I don't break things by accident. And by this I mean the old FreeNAS 11 docs; when I realized version 12 (of course now named TrueNAS) was released, I immediately went to read the "before updating" and "known impacts" section of the release notes, as is my custom. Imagine my surprise on being completely unable to find them! They're very obvious in the 11.3 release notes and go to some detail about the changes one might have to make to prepare for the update. But in the 12.0 release notes, there's no similar section, nor in the 12.0 U1 release notes.

Now, I suppose I could choose to believe that TrueNAS has reached such a state of perfection that there's nothing I need to take notice of, nothing that could go wrong. But the lack of detail in these notes, the almost comical lack of guidance in the Upgrading guide, and the tenor of several threads on this forum and Reddit's r/freenas have all rather shaken my faith in the whole thing.

 

[horizonbrave]

Just my 1 cent: I know resources are limited but good documentation will make sure that the Free/TrueNAS myth will live forever, acquiring both new and paying users.
Having limited resources it's not a good excuse and researching for a better economic model (and revenues) should be priority if that's the case. Unraid charges a "little" fee and even you guys could create more income by charging your user base a little or creating an affordable subscription model. We need quality and we are aware than that come with a price tag.

 

[horizonbrave]

once documentation has reached its "complete" phase

Is it noted anywhere in the documentation that is not complete?
Transparency and honesty goes a long way especially, no need to say.
And you have at stake the trust of thousands users.

 

[morganL]

I immediately went to read the "before updating" and "known impacts" section of the release notes, as is my custom. Imagine my surprise on being completely unable to find them! They're very obvious in the 11.3 release notes and go to some detail about the changes one might have to make to prepare for the update. But in the 12.0 release notes, there's no similar section, nor in the 12.0 U1 release notes.

Now, I suppose I could choose to believe that TrueNAS has reached such a state of perfection that there's nothing I need to take notice of, nothing that could go wrong. But the lack of detail in these notes, the almost comical lack of guidance in the Upgrading guide, and the tenor of several threads on this forum and Reddit's r/freenas have all rather shaken my faith in the whole thing.

Hi Jon,..
The upgrades to 11.3 did have more significant negative impacts. TrueNAS 12.0 has had it bugs (all reported), but fewer of the deliberate function removals. Please let us know if there are any "known impacts" that should have been reported but are not in release notes. We will add any issues to the "Known Issues" table.

We do acknowledge that the 12.0 documentation was not complete for Release... we were relying on 11.3 documentation being adequate for most use cases. The functionality and UI between 11.3 and 12.0 dod not change that much.. underneath the covers, OpenZFS changed quite a bit.
Morgan

 

[morganL]

Just my 1 cent: I know resources are limited but good documentation will make sure that the Free/TrueNAS myth will live forever, acquiring both new and paying users.
Having limited resources it's not a good excuse and researching for a better economic model (and revenues) should be priority if that's the case. Unraid charges a "little" fee and even you guys could create more income by charging your user base a little or creating an affordable subscription model. We need quality and we are aware than that come with a price tag.

Thanks for the suggestion. However, we would prefer to keep the free open core model going.
We see this documentation issue as a temporary transition issue. Moving to a modular documentation scheme required an investment in retooling and restructuring in the short term. In the longer term we will be more efficient and nimble.

It's a fair point that we could have had a notice that 12.0 documentation was "not complete" when we released in October. We had this forum post instead. As of now, most topics are covered. Now we can improve each topic and focus on better organization of the docs.

 

[Stilez]

I've been working on adding/improving some pages on in-depth points that might be helpful but that IX might not get round to as quickly, if they focus (appropriately!) more on the UI and controls and more general usage. So far I've done:

• More depth on SMB/Windows Discovery
• Periodic snapshots
• Deduplication
• Entering custom timings for scvheduled tasks/snapshots (quick guide to cron-style schedules)

On my maybe-list as time allows, if IX don't get there first:

• zfs send/receive and replication (especially CLI) - often need to do it in a way that cant easily be done via Web UI, and if that happens it's not so intuitive for newcomers
• ACLs - though I only know how to use ACLs from CLI not Web UI :)
• Review the docs on ZFS primer, and pool design
• Review the docs on creating and maintaining/modifying a pool/datasets/volumes
• Decent tabular guide to some of the more useful tunables relevant to the more common TrueNAS use-cases
• Troubleshooting guide (symptoms -> possible causes -> outline of intial troubleshooting steps)

Anyone got things to consider for the list? Or want to join in? I can't write about things I don't know much about, but perhaps someone else can, or we can get an idea what's useful.

Also - should we start a new thread to track community ideas for what could do with addressing and sharpening in the docs?

It could be good for many reasons. IX can get ideas, so can other community users. We can get a sense about when people care enough to come to the forums, what they wanted from the docs but don't get. We can get ideas for what ought to be covered in topics that isn't.

 

[morganL]

I've been working on adding/improving some pages on in-depth points that might be helpful but that IX might not get round to as quickly, if they focus (appropriately!) more on the UI and controls and more general usage. So far I've done:

• More depth on SMB/Windows Discovery
• Periodic snapshots
• Deduplication
• Entering custom timings for scvheduled tasks/snapshots (quick guide to cron-style schedules)

On my maybe-list as time allows, if IX don't get there first:

• zfs send/receive and replication (especially CLI) - often need to do it in a way that cant easily be done via Web UI, and if that happens it's not so intuitive for newcomers
• ACLs - though I only know how to use ACLs from CLI not Web UI :)
• Review the docs on ZFS primer, and pool design
• Review the docs on creating and maintaining/modifying a pool/datasets/volumes
• Decent tabular guide to some of the more useful tunables relevant to the more common TrueNAS use-cases
• Troubleshooting guide (symptoms -> possible causes -> outline of intial troubleshooting steps)

Anyone got things to consider for the list? Or want to join in? I can't write about things I don't know much about, but perhaps someone else can, or we can get an idea what's useful.

Also - should we start a new thread to track community ideas for what could do with addressing and sharpening in the docs?

It could be good for many reasons. IX can get ideas, so can other community users. We can get a sense about when people care enough to come to the forums, what they wanted from the docs but don't get. We can get ideas for what ought to be covered in topics that isn't.

Thanks for all the contributions... they are greatly appreciated.

On your list, I'd vote for the Troubleshooting guide.. but perhaps its a section with multiple docs. It's a complex topic that many users need. They also need advice on how to document and report their problems so that experienced users can help more easily.

@joeschmuck has contributed a HDD troubleshooting guide. https://www.truenas.com/community/r...bleshooting-guide-all-versions-of-freenas.17/

 

[ornias]

I agree with the troubleshooting guide @morganL It's amazing how often we need to repeat ourselves here, on the forum, with pretty standard issues like upgrading jails.

 

[jgreco]

I agree with the troubleshooting guide @morganL It's amazing how often we need to repeat ourselves here, on the forum, with pretty standard issues like upgrading jails.

Upgrading jails? Sheesh. I started writing stickies years ago due to being tired of constantly repeating myself. It's much better to be able to refer someone to a comprehensive resource that anticipates and answers all the back-and-forth.

 

[Stilez]

A question on that, @morganL @ornias @jgreco :

Troubleshooting is a big area. Often the user cant say "I was setting ACLs and now I can't reach my files", sometimes its just "I can't reach my files and I dont know why".

Given the huge range of issues and situations, how can this be addressed systematically in some kind of troubleshooter framework?

It feels almost like it needs a guided online flowchart thing, which asks relevant questions depending on previous answers, or something. Even if various lines of troubleshooting end up at "ask the community".

In other words, I don't think a documents or table based format is a good idea for a troubleshooter, for a product like TrueNAS. But I do think its the first places minds will go, both at IX and here.

It feels like the first questions ahould be metaquestions, like "how to approach it" and "what framework/methodology suits the needs?"

1. How can a *good* troubleshooter be created? At least for common use cases and ruling in or out, basic matters.
2. A good troubleshooter feels fundamentally different from a docs page/table. What tools.exist specifically for that purpose? Are there existing open source softwares, which can better provide a more intelligent or helpful guided troubleshooter, where community members can add as PRs, rules and statements that guide the user on new issues, and thereby update the troubleshooter easily enough that it fills out and becomes a good aide to solve many common symptoms?

 

[joeschmuck]

As someone who has written a lot of troubleshooting guides and other support documentation for the military, I can tell you that this can be a huge undertaking, no exaggerating at all. One thing you folks may want to think about is to as @Stilez mentioned, a Flow Chart. Create a graphical flow chart in maybe PDF and then decision blocks punt the user to a related Resource (or smaller troubleshooting guides) with hopes they can fix their problem. If you decide to make a full blow troubleshooting chapter then it's going to be a nightmare to maintain. Also place realistic expectations on what the troubleshooting section is to achieve and stick to it. You can't solve all the various problems that people encounter and you should expect a certain level of skill/knowledge from the users. Define assumptions because wrong assumptions will mess troubleshooting all up.

Whoever does this undertaking, I wish them the best.

 

[Stilez]

As someone who has written a lot of troubleshooting guides and other support documentation for the military, I can tell you that this can be a huge undertaking, no exaggerating at all. One thing you folks may want to think about is to as @Stilez mentioned, a Flow Chart. Create a graphical flow chart in maybe PDF and then decision blocks punt the user to a related Resource (or smaller troubleshooting guides) with hopes they can fix their problem. If you decide to make a full blow troubleshooting chapter then it's going to be a nightmare to maintain. Also place realistic expectations on what the troubleshooting section is to achieve and stick to it. You can't solve all the various problems that people encounter and you should expect a certain level of skill/knowledge from the users. Define assumptions because wrong assumptions will mess troubleshooting all up.

Whoever does this undertaking, I wish them the best.

This, totally.

There need to be realistic limits. Two.kinds of approach come to mind:

1. A kind of.basic troubleshooter that starts with simple symptom questions (you see this symptom? Check out these things).
2. Something that goes.for the 80/20 rule, and tries to maximise the useful case-outcomes (common symptoms/issues) for minimum work.

 

[Pierce]

Does this project need a professional technical writer ? my wife is a very good one, has a BS in Technical Journalism, and 40+ years experience in documenting everything from operating systems internals and user facing stuff to electronic design automation software. she's semi-retired (as in, not currently working, but would take another job if it was interesting), and is quite familiar with documentation production and process from old school Word and Framemaker to SGML, DITA etc online doc creation, AND has been telecommuting for many years. She far prefers writing to managing, but she's done both, including staffing complete publications departments for startups.

I haven't asked her if she's interested, and I won't unless you guys are looking for someone :D