Register for the iXsystems Community to get an ad-free experience and exclusive discounts in our eBay Store.

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

Western Digital Drives - The Preferred Drives of FreeNAS and TrueNAS CORE

Stilez

Senior Member
Joined
Apr 8, 2016
Messages
465
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 :grin::grin: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.

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

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

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

  1. 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;
  2. to close as WONTFIX;
  3. 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
  4. 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:

ornias

Senior Member
Joined
Mar 6, 2020
Messages
473
Dude, you just wrote an article requesting IX to copy-paste one doc-system to another.
That could've been done in one scentence:
"Hi, Mind making some time to copy everything relevant from the old wiki to the new one?"
 

Stilez

Senior Member
Joined
Apr 8, 2016
Messages
465
Dude, you just wrote an article requesting IX to copy-paste one doc-system to another.
That could've been done in one sentence:
"Hi, Mind making some time to copy everything relevant from the old wiki to the new one?"
Indeed, for what seems good reasons. A simple statement "Plz move stuff over" isn't really compelling, IX doesnt have infinite resources. To motivate a significant action, one needs to show something's actually a problem as-is, and worth the prioritising. Based on Jira, IX doesn't believe/appreciate that, and the in-house view right now is that the 12-docs can be fixed at leisure. I dont think, given their current state, that IX appreciates how poor they are, or the degree they are relied on, or they wouldn't allow v12 to reach RC1 and its docs still be in such a dire state compared to 11.3. It's tagged as WONTFIX with a vague but timeframe-less agreement it's a problem. So its not enough to just say "move it over". One needs to show IX the concern, the reason, the need, the urgency, and why proposed responses aren't really going to cut it. But yes, that would be the one line version of the request :)
 

ornias

Senior Member
Joined
Mar 6, 2020
Messages
473
@Stilez Must have missed this issue of yours, Got me a link for the Jira?
Might send a PR to get this fixed this week or the next!
 

Stilez

Senior Member
Joined
Apr 8, 2016
Messages
465
@Stilez Must have missed this issue of yours, Got me a link for the Jira?
Might send a PR to get this fixed this week or the next!
Link's in the very top of the OP. But the actual Jira issue was marked private, which I'm guessing, means not visible to the public? If you cant see it, that's why. No idea why, doesnt seem anything private about it at all. None of my other Jira issues are.

(also if you did, or can help any way, thank you!!!)
 

Kris Moore

VP of Engineering
Administrator
Moderator
iXsystems
Joined
Nov 12, 2015
Messages
410
@Stilez

With as much text as you contributed above, you could have re-written most of the docs as is ;)

That said. We've not hidden the 11.3 docs in any way. They are available right from the new docs site on the top-drop down, and will remain so for as long as they are useful. The docs on 12 are taking a bit of a different direction. Instead of a 150+ page "manual" we're focused more on instructions of how to accomplish specific tasks, so users are not expected to sit and digest a ton of pages to know how to go setup some specific thing.

If you have specific sections from the 11.3 guide that you feel aren't yet covered on the 12.0 docs site, please open specific tickets with a link to that section, and we'll get it in the queue to get written. It takes time, and we're still adding lots of content as we go here. If you are so inclined, you are welcome to help by creating a pull-request as well. We usually review and merge those fairly quickly.
 

Stilez

Senior Member
Joined
Apr 8, 2016
Messages
465
@Stilez

With as much text as you contributed above, you could have re-written most of the docs as is ;)

That said. We've not hidden the 11.3 docs in any way. They are available right from the new docs site on the top-drop down, and will remain so for as long as they are useful. The docs on 12 are taking a bit of a different direction. Instead of a 150+ page "manual" we're focused more on instructions of how to accomplish specific tasks, so users are not expected to sit and digest a ton of pages to know how to go setup some specific thing.

If you have specific sections from the 11.3 guide that you feel aren't yet covered on the 12.0 docs site, please open specific tickets with a link to that section, and we'll get it in the queue to get written. It takes time, and we're still adding lots of content as we go here. If you are so inclined, you are welcome to help by creating a pull-request as well. We usually review and merge those fairly quickly.
Thanks, Kris, and truly sorry/not sorry for having felt I need to write this. But your comments dont reassure at all.

The problems are as I have described, not ones that individual users can easily address by Jira tickets. It's like saying "please file a ticket for each pothole on a truly bumpy uneven street", rather than one ticket to resurface the entire road. The guidance isnt there how users can do it either, so that idea's dead: There isnt a framework of pages to be able to say what's missing, because too much is missing to identify what the individual jira tickets should each contain. One issue per control that doesnt have a description? One issue per UI page with a list of controls? One per core concept? One per "specific task" (and what counts as a "specific task"?).

You'd probably get 100-200 tickets and it would be worthless. The need is to migrate+update the info from 11.3 to 12-hub, and fix the UX points, please. But a ticket for each issue first? That's simply not sensible to ask, because too much is missing to even guess what those tickets would each cover, if one tried to.

The problem with "how to accomplish specific tasks" is, that the specific tasks do in fact need the detailed knowledge, so the pages wont all be soundbite length. Creating a pool requires the user to know or appreciate enough about sync/async, SLOG/none, mirror/raidz, removal capability for different layouts, compression options, to make the choices required for pool creation appropriately for their needs. Why? (1) The user will user TrueNAS features that are affected by those choices, (2) Those are essential considerations integral to the job, (3) They need to know how to select options in quite a few controls, when doing the task.

So from here, what you *think* you've got is task focused guidance. What I feel you've *actually* got is precious little guidance at all. A user can not even reliably perform the fundamental task of creating a pool without issues, using the v12 RC1 docs hub. It's that bad.

The fallback, create your own PRs? Well, suppose I put in solo work to refactor the 11.x guide as v12 mini docs. Is there a style guide that tells me how you envisage "instructions of how to accomplish specific tasks"? How the guide should be chopped up and collated anew? A list of "specific tasks" you want users to know how to do competently? There isnt any of it. My time = wasted if I tried. I have no vision what you want user efforts to look like. There's no guidance for contributors that explains properly, what makes a useful contribution.

You comment the hub contains v11 docs. Thats a negative, not a positive. Such 11.x docs as are there, are a mix of the relevant and the redundant. Things on 11.x will actively be wrong on 12. Things needed for 12 will be missing on 11.x. You actively do *not* want users on 12, looking up 11.x guidance and following it, because so much is new. You can't even just filter the search on v12, either.

Please, just look from a new user or even experienced user viewpoint, once 12 is out.

The only question that matters is, when 12 comes out, with many new things, can such a user use the guide to operate, configure and manage it.

I can't and I'm even experienced. I'm alarmed that at RC1, they can not.
 

ornias

Senior Member
Joined
Mar 6, 2020
Messages
473
@Kris Moore
I was looking at it and might I suggest a common ground:
Migrate the old manual (which is also still being maintained) to the new hugo based system, besides the goal-oriented manual?

As far as I can see, what needs to be done:
1.
The RST files here, need to be turned into markdown:

I've done some research and pandoc seems to be 95% effective in transcribing that into markdown (mostly just some references to <div> and %brand% that are not transcribed well).

2.
Said markdown needs to be put into the new folder structure

3.
Image references needs to be re-linked

That would be mostly it afaik.
I'm open to work on migrating it if @Kris Moore greenlights so.

@Stilez
He is right though, in the time I spend researching how to migrate this, you have writen half of your complaint... In the time you spend on your OP you could've actually migrated a LOT of the old manual to the new one :')
 
Last edited:

Constantin

Vampire Pig
Joined
May 19, 2017
Messages
890
Writing manuals to cover specific tasks is commendable for "plain vanilla" servers. This is the market that the likes of Netgear, QNAP, and Synology are targeting, i.e. coupling a splashy UI with basic functionality. A lot of stuff is abstracted from the user on those platforms - i.e. add a cache and the system will take advantage of it automatically.

Where TrueNAS and FreeNAS are dramatically different is in their flexibility. Yes, the GUI puts some restraints on things but we have plenty of users who are happy to drop down into the command line and do fun stuff like partition a stick of optane into two for a SLOG and L2ARC.

Key to that versatility is understanding the basics of how FreeNAS / ZFS works and how to royally muck things up. So reference articles with depth are a must. This is not an Apple device where important UX functionality is allowed to stay hidden unless the user holds the cursor in the right place while chanting the right incantations.

No matter what, the ZFS learning curve is steep and I expect that iXsystems will continue down the path of segmenting UX menus along the lines of advanced vs. basic to the point where less experienced users can safely set up a NAS in little time. That in turn will retain more users who otherwise would throw up their collective hands and migrate to UnRAID or whatever.

So there is a case to be made for the original documentation being around to explain what ZFS is, how it works, and what common pitfalls to look out for. At the same time, it would be awesome for new users to be able to follow along in a cookbook-like fashion to set up a simple media NAS.

To me, it should start with fitting out a Mini XL, then setting it up as a SMB server. Step by step, every user, pool, and share along the way. Then offer other modules, that explain topics such as ACLs, TimeMachine, etc. beyond a simple SMB NAS. Ideally, do it via YouTube videos with narration and screen sharing as that will minimize menu hunting frustration.
 
Last edited:

Stilez

Senior Member
Joined
Apr 8, 2016
Messages
465
If it's going to be redone as small tasks, then perhaps break it down like this (as examples):

EXAMPLE MAIN TOPIC
  • Creating a pool
Sections (might include):
  • Pool design concepts
  • Choosing a pool structure
  • Deduplication
  • Compression
  • Encryption
  • ZIL/SLOG
  • L2ARC
  • Special vdevs
  • Pools with special purposes (tips for pools that handle database, torrent, SMB or other things where there are known useful settingsa)
Each section is a short summary of a few sentences that gives the key information, plus a link to a standalone article expanding on that sub-topic, if relevant. That way a user can digest what the need, ignore the rest?

The outcome would be in this case, 10 standalone articles - one being an overview of creating a pool, the others being standalone articles covering "what are the basic concepts", "How do I choose a pool structure" (raidz/mirror considerations), "Should I use dedup and what do I need to know?" etc

So it's as intended, a larger number of small standalone topics, but also, linked from main articles covering larger tasks such as "creating a pool" that break them down into those smaller topics.
 
Last edited:

morganL

Captain Morgan
Administrator
Moderator
iXsystems
Joined
Mar 10, 2018
Messages
268
If it's going to be redone as small tasks, then perhaps break it down like this (as examples):

EXAMPLE MAIN TOPIC
  • Creating a pool
Sections (might include):
  • Pool design concepts
  • Choosing a pool structure
  • Deduplication
  • Compression
  • Encryption
  • ZIL/SLOG
  • L2ARC
  • Special vdevs
  • Pools with special purposes (tips for pools that handle database, torrent, SMB or other things where there are known useful settingsa)
Each section is a short summary of a few sentences that gives the key information, plus a link to a standalone article expanding on that sub-topic, if relevant. That way a user can digest what the need, ignore the rest?

The outcome would be in this case, 10 standalone articles - one being an overview of creating a pool, the others being standalone articles covering "what are the basic concepts", "How do I choose a pool structure" (raidz/mirror considerations), "Should I use dedup and what do I need to know?" etc

So it's as intended, a larger number of small standalone topics, but also, linked from main articles covering larger tasks such as "creating a pool" that break them down into those smaller topics.
Yes, 12.0 Documentation is incomplete. It will be better by RELEASE and keep improving. Most topics are still covered by 11.3 User Guides.

The good news is that the new documentation site allows user contributions and corrections. So, it's one step backward and some giant steps forward. Volunteers who can transcribe their wisdom and experience are sought. Perhaps we should start a Documentation sub-forum?
 

ornias

Senior Member
Joined
Mar 6, 2020
Messages
473
@morganL While the previous docs aren't the easiest to edit, they are editable quite well too ;)
 

danb35

Wizened Sage
Joined
Aug 16, 2011
Messages
11,567
Instead of a 150+ page "manual" we're focused more on instructions of how to accomplish specific tasks
The idea of instructions to accomplish specific tasks is a good one, and it's an area in which, historically, the FreeNAS docs have been pretty deficient. They've generally been an excellent reference (not as much with 11.2+, but certainly before that), such that if you want to know "what does this button do?", it's there--but if you want to know, soup to nuts, "how do I set up a SMB share", they weren't very good. Hence a number of third-party guides to try to do that, one of which I host on my own wiki (and at one point, one of your folks was trying to move to your wiki, before you killed it, again*).

But the idea that you should do that instead of a thorough reference is, if you'll forgive my bluntness, nonsensical. Let's take the example I mentioned above of creating a SMB share, and look at a very simple case. The user needs to:
  • Create a user
  • Create a dataset (fine, the share doesn't have to be its own dataset, but that's a commonly-recommended best practice) owned by that user (groups and more advanced permissions scenarios can be deferred, but really should be addressed too)
  • Create a share pointing to that dataset
Each of those steps has dozens of options, and most can, in most cases, safely be left at their defaults (if the defaults weren't good enough, they wouldn't be the defaults, right?). But the reason you've exposed those options is that you expect users will, at least occasionally, need to change them, and that means they need to be documented. And to do that, there are a few options:
  • Make the "how to set up a SMB share" article 10x longer than it needs to be by explaining every option (and doing so differently than every other place those options will be explained)
  • Link to the reference docs for explanations of the options not addressed in the how-to article
  • Or just leave the user on their own to figure it out
I think it's obvious the second is the best way to go--but that means the reference docs need to exist, be complete, and be up to date.

Edit: I understand that both kinds of guides take resources to produce, and it's possible that you may not have resources available to do both before -RELEASE. In that case, IMO, the reference guide needs to be the priority. The community can much more easily fill in gaps in "how to do X" documentation (as we see in many places, including Uncle Fester's Guide and the resources section of this very forum) than we can fill in "what does this option do?" And if you're going to take the position that (to make up a number) 98% of the 11.3 guide still applies, then 98% of your work is already done--and you're in a much better position to know what's changed than we are, since you changed it.

* It seems worth pointing out that iX' treatment of community-provided documentation has been, well, inconsistent at best. I think the clearest example of this is the iX wiki, which has been up at least twice, and was taken down. So you might find that many people will be a little hesitant to spend their time contributing to this iteration of your docs rather than putting their work somewhere where they have control over it.
 
Last edited:

Evertb1

Neophyte Sage
Joined
May 31, 2016
Messages
559
Since 2016 I am a (happy) user of FreeNAS (and now TrueNAS Core as well) and a frequent visitor of this site. In those years I have learned quite a lot about FreeNAS by reading the manual, doing research and asking questions on the forum.

At a certain point I felt free to answer questions of other forum users and every now and then point out there is a quite usefull manual available that is not hard to use. I have always been of the opinion that with appliances like FreeNAS/TrueNAS Core you need to be your own helpdesk. So reading the manual should not be to much of a hardship and you must be willing to show that you at least made the effort, before you ask something on the forum.

A day ago I encountered a very basic question that should be really easy to answer by just reading the installation instructions of TrueNAS. So I almost wrote back "rtfm". I mean, the documentation section is not that hard to find on the site. But before I became nasty about it I decided to look for myself at the documentation section of TrueNAS. I mean: what if it was not there? And guess what I found? Nothing useful. And certainly not enough to answer the question at hand. How can I in good conscience tell somebody to rtfm if it is not there or hard to find? If I am not mistaken we are at RC1 now. The documentation should be about in it's final stage.

To me it doesn't matter what format the documentation has. If it has a decent index and is organized in useful subjects, paragraphs, tasks or whatever I am happy. I can find my way around I think, but for new users the current situation is not encouraging. And how is a new user to know that a lot of what is covered by the FreeNAS manual also goes for TrueNAS?
 
Last edited:

Patrick M. Hausen

Dedicated Sage
Joined
Nov 25, 2013
Messages
1,915
Following up to @danb35 IMHO a complete reference documentation is indispensable whereas a "howto" style guide for various tasks is nice to have. Blunt as that statement may seem the latter can be filled in by the community while the former can't. And the experienced users who could provide the guides need the reference.
 

ornias

Senior Member
Joined
Mar 6, 2020
Messages
473
So I think everyone here agree's with my previous request in this thread to migrate the old docs where relevant to the new system, in addition to the new "how-to" style documentation?
 

danb35

Wizened Sage
Joined
Aug 16, 2011
Messages
11,567
I think everyone here agree's with my previous request in this thread to migrate the old docs where relevant to the new system
It'd be a whole lot better than nothing--but much better if it were updated to actually reflect what's in 12.
 

Dismayed

Member
Joined
Oct 17, 2015
Messages
26
I'm looking at cutting over from ZFS on OSX because Apple has obsoleted my mid-2010 Mac Pro, and the ZFS on OSX documentation is inadequate. I have gotten by by begging from help from experienced users, but I could have done a lot on my own with better documentation. So I'll delay building my new NAS until the TrueNAS Core documentation catches up with the development.
 

Tigersharke

BOfH in User's clothing
Administrator
Moderator
Joined
May 18, 2016
Messages
623
In the olden days when PC-BSD was still a thing, the documentation was developed on a wiki which enabled users to add their content and for admins or editors to improve or adjust submissions. I am not suggesting to use a wiki, but one other thing that we had on that PC-BSD doc wiki, was a basic framework which after the first few iterations of the handbook remained largely the same. I haven't looked at the state of the documentation that this thread critiques but aside from style guidelines (which I think we might have also had for PC-BSD), it would surely be helpful to have a framework to fill. We could point at specific sections of the present (11.x) documentation for inclusion but it would be as easy to point at the whole because it seems that the intent of the tightly focused "quick guide" format is a bit ambiguous or uncertain for many of us.

A sketch, an outline, can be filled or revised, but it is much more difficult to flesh out a blank page.

One comment in previous posts was to have the quick succinct guide also indicate or link to more in-depth articles or documentation. This is a happy medium, and with some disclaimers could even direct users to specific well-written resources on these forums. A two part approach is reasonable, even if it is accomplished by lifting out very specific tidbits from the in-depth manual to be placed within a quick guide nearly verbatim.
 

Evertb1

Neophyte Sage
Joined
May 31, 2016
Messages
559
When it comes to a manual I wasn't unhappy with what we use to have with previous versions of FreeNAS. Maybe not perfect but usable. And having a link to it in the GUI was not bad as well. They say that beggars can't be choosers and a lot of the forum users are using FreeNAS/TrueNAS for free. So maybe we are not exactly entitled to have a good manual and just must wait and see if and when we get something useful. On the other hand I can't imagine that iXSystems has no interest in a decent, well maintained manual. After all, this community is a (small?) part of the kitchen were yet a better iteration of FreeNAS/TrueNAS can be cooked up.

To be honest, I don't think it's the role of users to write and maintain the basic user manual. I am working as a corporate software developer for over 25 years now and never in that time I dared to propose that a user group wrote a manual for the software my teams developed. That would be my last day on the job I think. Also in those years, I have learned the hard way, that writing tests and manuals after the developing stage is a very bad idea. The day you start developing is the day you start writing tests and documentation (including technical and user manuals) as a part of the developing process not as an afterthought. Maybe that's why I don't understand the need for this discussion very well. To me having a user manual is a given.

How To guides are a different thing all together. And while they may reference to a manual here and there they are not the manual. I think they will never be a substitute for a decent well structured manual. That being, said having a nice collection of them for a diversity of jobs is very nice. And I don't see any reason why those can't be written by users that are experienced in those jobs. Of course if iXSystems came up with a bunch of them I would not complain.

There are problems with that of course. First of all it takes effort to keep them handy and indexed in such a way that they can be found easy for years to come. And providing a safe haven for them -being it a Wiki or whatever- asks for commitment of someone or some company. And not just for a week but for years to come.

Another problem is that they need to be maintained as well. To give your all, and being committed to write a nice How To is great to do once. But maintaining your work asks for even more commitment. Your nice How To might not survive the next version of FreeNAS/TrueNAS without a major overhaul.

So all in all there are problems to resolve but the basic manual should not be a problem, it just should be there.
 
Top