I asked this on Jira (DOCS-1015) and it got tagged as "WONTFIX".
I'm trying to imagine newcomers or even somewhat experienced users, handling TrueNAS CORE 12 when it's released, using the present guide.
The standard of the docs hub is - I'm sorry to use the word - awful to abysmal. It's extremely thin and patchy at best, at present. I've let it be a while, but really *really* not happy still. Every time I try to look something up - and I'm an experienced user not a newcomer - I'm reminded again forcibly how useles the new hub presently is.
It isn't okay that way. really not. Users need that stuff daily to manage their NAS.
I'm frustrated and unhappy at the apparent view that users docs can be effectively 80% removed for 12-REL compared to 11.3, and somehow it wont matter much to anyone. Hence this post, and hence also tagging for @Kris Moore as an active ixPerson
on the forum who understands the importance of docs more than most. To see if it's just me, or what might be achievable to at least patch over the dreadful draft docs condition, before 12 is final.
The docs hub and its missing info
Before specifics, I want to answer 3 possible responses/objections/considerations.
My concern, therefore, is with the loss of existing information and non-easy-findability of whatever few dribs and drabs of information are in the new hub. Not with the change of format to shorter more narrow focus articles.
When users need to rely on guidance for a major new release, and can f** up their server, enjoyment, and pool, if that guidance is shoddy, and when we already have really good guidance, why has that guidance not been at least copypasted in chunks to the new hub, during the development of new docs pages? Just to tide people over during the time new docs in the new style will take to update and write?
It's hard to pick specific examples, because it's so darn prevalent throughout the new hub. I could literally pick *almost any* page in the docs hub, point to the equivalent section in the 11.3 docs, and the loss (or at best non-findability) of crucial information is shocking.
Ditto so much else. Controls which had their options explained before, and have perfectly good explanations, now the controls themselves don't get even mentioned, the user presumably has to guess or use the tiny tooltips to know. Considerations that can be crucial are omitted. Literally, *nothing* in the new docs hub is actually much good as docs, right now.
I hate being so negative but guys - what are you thinking?! Do you really want new and existing users managing on such weak and incomplete info when 12 comes out? When we already have proven powerful user guidance we could just migrate over to cover the hole somehow? Can't we at least migrate 11.3 to the hub format in small focused chunks, so it's there, *somehow*?
But... contributing?
I asked the question about the quality drop in v12 guidance, on Jira. The response was friendly, but still a total surprise. It was
What tools are needed for users to contribute? A style guide. Like, a *proper* style guide. There's a page marked "style guide" but it's actually just a syntax guide for markdown. There's a page called "Article template" which is better but still isnt a style guide either.
What is a style guide? Ask any technical documentation writer. Ask any coder. A style guide tells you how a page should look, the standard ways you want things to be written, formatted, and linked. It tells you phrases to use and avoid, "dos" and "donts"..... so the pages all have commonality. Does nobody actually know what a "style guide" is, or have experience of good documentation style guidance?
It helps to have a list of pages you want created, so we know we are being useful. Again, zero.
Beyond that, users are invited to write pages. That's workflow, and there is absolutely nothing on that. How much are IX authored pages "set in stone"? Does IX want 4 different alternative pages created about SMB config, if 4 users all want to write up something about it their own ways? Or if one page, how should users collaborate on it? Does the person who created a page get to say? Or do we all fork versions and waste our time, seeing which of the 4 IX will cherrypick when its done?
Users that IX invites to collaborate on docs, need to know their time won't be wasted. To do that, they need enough actual guidance on style and content and workflow, to be as sure as they can, about what they are writing, that it won't just be wasted effort. There's almost nothing of that kind present, and right now it looks like user contribution is stuck at minor typos and odd sentences where at least the result is more predictable.
Call to ixSystems
Please take this seriously. Users data matters - nobody knows this more than you. For TrueNAS (CORE or otherwise) the user docs are the rock which the config rests on, that defines and controls data storage and management.
User satisfaction matters a lot. Users ability to get their config right, is the most directly linked thing to user satisfaction with the platform and user woes. (Apart from only, bug fixes!)
You already have the text you need. You've already checked and scrutinised the wording of 98% of it. It just needs moving into suitable chunks for 12-REL guide on the new docs hub, and the anomalous appearing-disappearing sidebar inconsistency fixed. That's all. Or tell us that its okay if its not perfect but can we help move it over and update anything new in 12. I'm sure we would love to help you if you cant spare resources. Just reassure us the effort wont be a waste, and it'll be fine till the docs can get a proper makeover.
Please fix the more jarring/limiting hub UX issues - I'd highlight here the appearing-disappearing anomalous inconsistent sidebar, a search dropdown to restrict to a specific product/version/document (eg guide/release note), and a "more results" button.
But please do not just WONTFIX it, or kick it into the long grass till 12.1 or 12.2.
We need those docs now, and thats both newcomers and experienced users alike.
Please heed this and try and do something, and sorry for a long complaint/rant, which I'll end here :)
Feedback welcomed and appreciated, and - if I'm wrong please tell me.
I'm trying to imagine newcomers or even somewhat experienced users, handling TrueNAS CORE 12 when it's released, using the present guide.
The standard of the docs hub is - I'm sorry to use the word - awful to abysmal. It's extremely thin and patchy at best, at present. I've let it be a while, but really *really* not happy still. Every time I try to look something up - and I'm an experienced user not a newcomer - I'm reminded again forcibly how useles the new hub presently is.
It isn't okay that way. really not. Users need that stuff daily to manage their NAS.
I'm frustrated and unhappy at the apparent view that users docs can be effectively 80% removed for 12-REL compared to 11.3, and somehow it wont matter much to anyone. Hence this post, and hence also tagging for @Kris Moore as an active ixPerson
on the forum who understands the importance of docs more than most. To see if it's just me, or what might be achievable to at least patch over the dreadful draft docs condition, before 12 is final.The docs hub and its missing info
Before specifics, I want to answer 3 possible responses/objections/considerations.
- This is not a request for IX to divert significant resources. It's not like anyone has to write it from scratch. We have really good 11.3.x docs to just copypaste from, for 98% of it, until the new hub gets time for a makeover. It would be enough.
- This is not a complaint about guide to hub change. Long pages are tricky. If the *information* on the new hub was at all comparable to whats been removed, or wasnt so important for user guidance, I'd be fine with it. I didn't complain about the new UI, even when that was in development for a few versions, so I have track record of not objecting to radical change.
- This is not an issue able to be answered by "It's open source so people can contribute". First they can't easily do so (see below). Second it's about the removal of already-written content (in whatever format and UI it's presented doesn't matter), so that under v12, users needing that guidance would not be able to find equivalent knowledge in the hub. But they'll still need it. Badly.
My concern, therefore, is with the loss of existing information and non-easy-findability of whatever few dribs and drabs of information are in the new hub. Not with the change of format to shorter more narrow focus articles.
When users need to rely on guidance for a major new release, and can f** up their server, enjoyment, and pool, if that guidance is shoddy, and when we already have really good guidance, why has that guidance not been at least copypasted in chunks to the new hub, during the development of new docs pages? Just to tide people over during the time new docs in the new style will take to update and write?
It's hard to pick specific examples, because it's so darn prevalent throughout the new hub. I could literally pick *almost any* page in the docs hub, point to the equivalent section in the 11.3 docs, and the loss (or at best non-findability) of crucial information is shocking.
- Users will like the sound of dedup. Lets take that as an example, since it can be problematic. I've got the basics of ZFS, so I go to storage in the guide. Creating a pool section? No mention of any of the things users were told carefully, in 11.3. Create dataset section? Similar. Type dedup into search and I get release notes back to 11.1, but what I actually expect is a page about dedup in 12, the version I'm using. Is there anything? Take a guess. Try it yourself. Nothing. Blank. Useless. Nada.
- Let's continue. Ignore dedup. I've created a pool. Now I want to create a dataset, or configure the root dataset I just created. Let's look at the controls. Sync (inherit)? Guidance in the 12-guide: not even mentioned. Compression level (lz4)? Guidance in the 12-guide: not even mentioned. Can you guess what the outcome is for every other important option on that page? And thats a crucial UI page, creating the dataset you want, and avoiding problems you don't. Every user needs it. God knows what the rest is like.
- But wait, there's a link under "Creating a ZFS pool", right at the top of "Creating a pool". It says, "The way this is accomplished is through setting up ZFS Pools". Maybe that's the detailed help. No, wait, it isn't. It's an external link to the entire bloody Wikipedia article on ZFS. Oh god.....
- Perhaps we should try search. It's a hub and that's the idea, right? As I've mentioned: Good news - the docs hub has a search box. Bad news - its useless and indiscriminate. Try it yourself. Click "guide" from the v12 Web UI, get to the docs hub, and type what you're looking for. What you find could be out of date, even misleading for v12. Try terms like "sync" or "dedup" or "tunable". Even when you click "guide" in v12, there's no way provided to get a search just for v12-relevant pages. You get results indiscriminately from *every* doc in the hub. Docs from 11.1-U1 when you're on 12. FreeNAS if you're on TrueNAS (or vice-versa). Information correct for <=11.3 ZFS not v12 ZoF. Bonus frustration too - there's no cogent sort order, and theres no obvious way to see further search hits, whether they contain anything from v12 either.
- Moving to UX aspects. The new UI when you click "guide" initially comes up without a sidebar, making organised page location tricky. Blobs of vague topics on a page. But then as soon as you click any topic, a helpful sidebar now magically appears. Why isn't that there in the first instance? Why does the hub UX radically change when you are on the hub start page and then click through to a topic?
Ditto so much else. Controls which had their options explained before, and have perfectly good explanations, now the controls themselves don't get even mentioned, the user presumably has to guess or use the tiny tooltips to know. Considerations that can be crucial are omitted. Literally, *nothing* in the new docs hub is actually much good as docs, right now.
I hate being so negative but guys - what are you thinking?! Do you really want new and existing users managing on such weak and incomplete info when 12 comes out? When we already have proven powerful user guidance we could just migrate over to cover the hole somehow? Can't we at least migrate 11.3 to the hub format in small focused chunks, so it's there, *somehow*?
But... contributing?
I asked the question about the quality drop in v12 guidance, on Jira. The response was friendly, but still a total surprise. It was
- to tag the issue as "private", I'm guessing that means non-public? If so, its literally, the only issue of many issues/suggestions I've posted that was tagged that way, but there doesnt seem anything very private about it at all;
- to close as WONTFIX;
- to express sympathy and intent to fix it, but no specific timeframe, probably not for quite a while? ("I am keenly aware where content has not been ported with enough depth and that it's being addressed as quickly as I can get to it"). I believe the sentiment, and appreciate the reassurance, but it's not enough. Users need it *now* for 12-REL. Not in an unknown number of months time;
and - to comment it's good that users can contribute. Yay. (But even that isn't true. Users can't even contribute effectively. IX haven't given users the tools to do even that.)
What tools are needed for users to contribute? A style guide. Like, a *proper* style guide. There's a page marked "style guide" but it's actually just a syntax guide for markdown. There's a page called "Article template" which is better but still isnt a style guide either.
What is a style guide? Ask any technical documentation writer. Ask any coder. A style guide tells you how a page should look, the standard ways you want things to be written, formatted, and linked. It tells you phrases to use and avoid, "dos" and "donts"..... so the pages all have commonality. Does nobody actually know what a "style guide" is, or have experience of good documentation style guidance?
It helps to have a list of pages you want created, so we know we are being useful. Again, zero.
Beyond that, users are invited to write pages. That's workflow, and there is absolutely nothing on that. How much are IX authored pages "set in stone"? Does IX want 4 different alternative pages created about SMB config, if 4 users all want to write up something about it their own ways? Or if one page, how should users collaborate on it? Does the person who created a page get to say? Or do we all fork versions and waste our time, seeing which of the 4 IX will cherrypick when its done?
Users that IX invites to collaborate on docs, need to know their time won't be wasted. To do that, they need enough actual guidance on style and content and workflow, to be as sure as they can, about what they are writing, that it won't just be wasted effort. There's almost nothing of that kind present, and right now it looks like user contribution is stuck at minor typos and odd sentences where at least the result is more predictable.
Call to ixSystems
Please take this seriously. Users data matters - nobody knows this more than you. For TrueNAS (CORE or otherwise) the user docs are the rock which the config rests on, that defines and controls data storage and management.
User satisfaction matters a lot. Users ability to get their config right, is the most directly linked thing to user satisfaction with the platform and user woes. (Apart from only, bug fixes!)
You already have the text you need. You've already checked and scrutinised the wording of 98% of it. It just needs moving into suitable chunks for 12-REL guide on the new docs hub, and the anomalous appearing-disappearing sidebar inconsistency fixed. That's all. Or tell us that its okay if its not perfect but can we help move it over and update anything new in 12. I'm sure we would love to help you if you cant spare resources. Just reassure us the effort wont be a waste, and it'll be fine till the docs can get a proper makeover.
Please fix the more jarring/limiting hub UX issues - I'd highlight here the appearing-disappearing anomalous inconsistent sidebar, a search dropdown to restrict to a specific product/version/document (eg guide/release note), and a "more results" button.
But please do not just WONTFIX it, or kick it into the long grass till 12.1 or 12.2.
We need those docs now, and thats both newcomers and experienced users alike.
Please heed this and try and do something, and sorry for a long complaint/rant, which I'll end here :)
Feedback welcomed and appreciated, and - if I'm wrong please tell me.
Last edited:
