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

Status
Not open for further replies.

ornias

Wizard
Joined
Mar 6, 2020
Messages
1,458
It'd be a whole lot better than nothing--but much better if it were updated to actually reflect what's in 12.
Sure, but that update isn't that significant to be honest.
Mostly some screenshots and a few features that need to be documented.
 

ornias

Wizard
Joined
Mar 6, 2020
Messages
1,458
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.
Should they add a manual for us leechers? No.
But they also don't supply the manual for their enterprise (paying!) customers!

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.
Yes, a community shouldn't write your enterprise documentation. Period. You as a company are liable for your product and it's support, you can't shift that blame to the community.

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.
This is indeed a part where the community and IX could complement each other. If IX supplies a good manual and give a little push in the right direction, there are a lot of capable people able to add additional content like how-to guides

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.
The same can be said for any project documentation and yes, I am absolutely annoyed by the state of most opensource project documentations. It's rather odd actually, because keeping things synced and ordered isn't even that much of a time effort tbh.

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.
Currently there isn;t anything to maintain. I think thats a more significnat issue ;)

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

Patrick M. Hausen

Hall of Famer
Joined
Nov 25, 2013
Messages
7,737
Should they add a manual for us leechers? No.
Why was there ever a good exhaustive reference manual for 10.x, 11.x then? I don't understand why keeping the docs in sync with the current product is not part of their roadmap. The 11.3 documentation is excellent. It should simply continue to exist in the same format for future releases.

The "how do I ..." problems can be solved by community support.

Kind regards,
Patrick
 

danb35

Hall of Famer
Joined
Aug 16, 2011
Messages
15,456
Sure, but that update isn't that significant to be honest.
Significant for whom? Us or iX? For iX, who made all the changes and presumably knows what they changed, it shouldn't be a big deal at all to update it to match 12. For us, not so much.
 

Stilez

Guru
Joined
Apr 8, 2016
Messages
529
One aspect - the docs hub search - can't be fixed by community users so I've suggested it on JIRA:
As well as populating accurate content, a user needs to be able to search for guidance on their specific version, not all versions, and specific kinds of resource. If you want to set up encryption, or a pool, there are fundamental differences/changes between different versions, and if a user picks up 11.x docs by mistake, it may not work, may misinform, and will generally be Very Bad. Similar, if you want official guidance you might not want the results full with press releases, or release notes, or community pages.
 
Last edited:

Stilez

Guru
Joined
Apr 8, 2016
Messages
529
Several people mention a wiki, and immediately dismiss the idea, but I'm not actually sure why they do dismiss it...

Why *not* set up docs.ixsystems.com, or wiki.ixsystems.com, and migrate all docs there? Its nearly an Ideal format. Pages could link at their footer to previous versions of the same page to handle new versions ("see this page for 11.0, 11.1, 11.2, 11.3..."), search is built in, formatting is more widely understood than markup/markdown/RST (but convertible by script), ....

Community contributor discussion would be easier (discussion pages), nothing gets lost, and if there are things that aren't docs but still fit into the same format, it's flexible for that too. The MediaWiki software widely used, allows you to limit who can approve changes, and allow them to appear on the Wiki, by restricting authorisation to make changes, and also by restricting visibility of changes. So you have a very good range of controls for IX staff, more trusted contributors, others. I use OPNSense router (on a hardened variant of FreeBSD) and their docs is done that way, it works well. It would fit the "documentation hub" model of smaller pages, or indeed any model wanted, so it doesn't run against current ixSystems staff thinking.

Github isn't sacred. Should it be suggested to do exactly that? As it may solve various docs issues and improve workflow? Or are there reasons not to?
 
Last edited:

danb35

Hall of Famer
Joined
Aug 16, 2011
Messages
15,456
Several people mention a wiki, and immediately dismiss the idea, but I'm not actually sure why they do so..
Because iX have killed off their own wiki at least twice already. Why would I put effort into putting docs up there, just to have them kill it again?
 

Stilez

Guru
Joined
Apr 8, 2016
Messages
529
Because iX have killed off their own wiki at least twice already. Why would I put effort into putting docs up there, just to have them kill it again?
Fair - that's olden times stuff I didn't know, or I wouldn't have asked. Thanks for the explanation!
 

Kris Moore

SVP of Engineering
Administrator
Moderator
iXsystems
Joined
Nov 12, 2015
Messages
1,448
@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 :')

@ornias Yes, you and anybody else that wants to help us convert the old-style guide to markdown would be more than appreciated, and we'd be happy to include it in the official docs / hugo site. We've been swamped lately with all the tasks around 12.0 launch, but would be happy to help sanitize / format the document if you get a pull-request opened. It would be good to list it in the reference section of the new site, and once in markdown, it'll be easy to pull from to flesh out other parts of the site, or just link directly to in how-to style articles.

I do very much appreciate all the interest in this topic as well. Moving to a new-style docs system is no small task, and for the size of team we have working on it, we've made huge progress for 12. However, there is obviously more to do, screenshots to take, reference docs to port over. It's going to be some time to get all that done and finished to the state we want, but rest assured, it is happening.

Any cycles the community can help to make this go quicker will be much appreciated, and the new site / markdown format makes it virtually painless to help contribute content. If you can figure out how to use Xenforo and write forum HOWTO's, you can just as easily add content or a HOWTO on the official docs site. Making this as easy as possible was the goal, since our forum users tend to write awesome content, but it gets lost on the forums over time. We wanted to make sure this great content could just as easily live on over on the docs site, and allow others (iX included) to ensure it gets updated as the software evolves.
 

Stilez

Guru
Joined
Apr 8, 2016
Messages
529
@ornias Yes, you and anybody else that wants to help us convert the old-style guide to markdown would be more than appreciated, and we'd be happy to include it in the official docs / hugo site. We've been swamped lately with all the tasks around 12.0 launch, but would be happy to help sanitize / format the document if you get a pull-request opened. It would be good to list it in the reference section of the new site, and once in markdown, it'll be easy to pull from to flesh out other parts of the site, or just link directly to in how-to style articles.

I do very much appreciate all the interest in this topic as well. Moving to a new-style docs system is no small task, and for the size of team we have working on it, we've made huge progress for 12. However, there is obviously more to do, screenshots to take, reference docs to port over. It's going to be some time to get all that done and finished to the state we want, but rest assured, it is happening.

Any cycles the community can help to make this go quicker will be much appreciated, and the new site / markdown format makes it virtually painless to help contribute content. If you can figure out how to use Xenforo and write forum HOWTO's, you can just as easily add content or a HOWTO on the official docs site. Making this as easy as possible was the goal, since our forum users tend to write awesome content, but it gets lost on the forums over time. We wanted to make sure this great content could just as easily live on over on the docs site, and allow others (iX included) to ensure it gets updated as the software evolves.
@Kris Moore - This is really welcome, and very constructive! Thanks!

Here are my thoughts how to make it a reality, given the timescale for it all. Which is probably under 3-4 weeks now.


I think we need to move fast, and this is roughly what I propose, if agreeable, to leverage the community and allow us to work fast, as IX wants, and without major issues arising. The aim would be, to get it "good enough for 12-REL".

First, I think it's *got* to be a joint effort. Not just "as a broad principle" or "you can contribute" (the usual things people say), but because it can literally, only be achieved in a 12-REL timescale, by both community and IX working together as a collaborative focused project. There are things that people here can do, but some aspects of it that we badly need IX input, help, and guidance - and *not* via the slow "one item = one issue" method of Jira or Github.

Community members (self included) would be glad to help convert, update, refine, and review 11.3 docs, pull it to usable "docs hub" chunks, and PR it for v12 docs. I have no doubt of that, especially given the amazing offers to undertake and support the work by so many experienced users and fans. We can do it, and it'll speed IX work an order of magnitude, and free resources, and quite likely get 12-docs complete, on the hub, and ready in *some* form (even if not perfect! Enemy of good!) for 12-REL.

But to do that, we will surely need real help from IX too.

We can't afford to do it, only to find its all wrong in your eyes, or start over again. We cant afford long waits for replies to check if stuff looks broadly okay in approach, because so much needs checks beyond the technical wording. The technical wording is the smallest issue this time around (the 11.3 docs are already IX-scrutinised and we'll get most changes right where changes are needed). The big ones are things like - are the chunks we've broken stuff into okay? Are the topics roughly the right size? Are we striking the right notes? And that's before technical review of content itself.

So we will need need someone IX, or IX trusted, with part of their tasked role being "on the project team" who is our point contact, engaged with the effort, authorised to yesno what community members do, or want to check, so we can get it right quickly and surely, and who can make the decision to actually "sign off"/commit chunks as they are done, as "good enough for a first cut".

The technical review can probably be trusted to the community in the first instance. That's not usual, but probably justified for this one time (Perfect enemy of good!). Nobody inexperienced is going to do something like this. So trust us on the broad content (we can FIXME or CHECKME flag anything we aren't sure of to be dealt with in one go), and focus on information conversion and a decent "first go". We'll get it right enough for release, and with point-person help, we will also get sit formatted and styled professionally enough to pass. It can then be given a brief technical review for serious issues, as chunks are done - and we can polish anything else afterwards.

That's how I'd approach it, and I think it could work. But the key needs are really needed, I think, if it's to stand a chance. Namely:
  • Working together for real (joint project style) not just Jira/PR style. An informal ad-hoc project group of community folks, plus at least some modest hours daily by some IX person, or someone IX trusts to help and be our point-go-to person (see next item). Give us a forum thread or better a github docs branch we can freely work on/mangle, to discuss anything that needs answers or discussion.
  • Allocate someone part time who is tasked with helping and given enough time (2 hrs a day maybe???) to quickly turn around our collaborative queries, and authorised to decide in the first instance queries on whether something's ok or how IX would want it. Their role is to (1) guide/help us be sure we write in a way that fits IX vision, (2) occasionally escalate and get answers from within IX on technical points that may occasionally come up, if we as volunteers can't figure it out, and (3) commit chunks to the hub if happy with them as we do them. Not really to do technical review.
  • Having done that, trust us to get a first cut decent enough with their help/guidance/input, and flag most "non cosmetic" technical queries/factchecks, in other words bypassing the usual rigorous review of everything. Trusting we catch 98% of it and it's "good enough" for a first usable cut.
  • And therefore, limit further IX review to a quick "skim read" technical review for "good but not necessarily perfect" and "nothing seriously wrong", once chunks are done (because your person on the team will have guided most of it already!) Just use it. Save further refinement for PRs and/or after 12-REL.
It'll be good enough, and fast. Can we have those few things? A group github docs branch (and forum thread perhaps), someone who can okay/commit/guide stuff with a couple of hours allocated a day at a guess, and a free hand to move fast and be trusted to autonomously get a first cut thats "good enough for now", without being held back by slowness inherent in usual processes.
 
Last edited:

ornias

Wizard
Joined
Mar 6, 2020
Messages
1,458
Why was there ever a good exhaustive reference manual for 10.x, 11.x then? I don't understand why keeping the docs in sync with the current product is not part of their roadmap. The 11.3 documentation is excellent. It should simply continue to exist in the same format for future releases.

The "how do I ..." problems can be solved by community support.

Kind regards,
Patrick
Don't cherry pick my comments.
They shouldn't have to make a manual JUST for us leechers, but should for their paying customers. like the whole post you quoted goes on about.
 

ornias

Wizard
Joined
Mar 6, 2020
Messages
1,458
@ornias Yes, you and anybody else that wants to help us convert the old-style guide to markdown would be more than appreciated, and we'd be happy to include it in the official docs / hugo site. We've been swamped lately with all the tasks around 12.0 launch, but would be happy to help sanitize / format the document if you get a pull-request opened. It would be good to list it in the reference section of the new site, and once in markdown, it'll be easy to pull from to flesh out other parts of the site, or just link directly to in how-to style articles.
Thanks Kris, that was the green light I was holding out for...
I'll try and send you a WIP migration by friday this week.
 

Stilez

Guru
Joined
Apr 8, 2016
Messages
529
Thanks Kris, that was the green light I was holding out for...
I'll try and send you a WIP migration by friday this week.
I'd love to help. Just extremely apprehensive of putting the work in only to have it not work for IX. But once there's a rough first cut, then im happy to give some time and contribute to making sure its usable, and adding the "glue" pages.

By glue pages, I mean, when you break down a long 11.x page into small bite size chunks for the IX dkcs hub concept, 2 things happen. (1) The long 11.3 pages must be split into v12 short topics, and formatted appropriately. That's mostly but not totally scriptable, as there is judgement in how they split. (2) the hub will need additional "task/topic overview pages" ("glue pages") because higher level tasks such as "create a pool" will now only outline the process briefly, with links to those smaller separate pages for the individual steps and considerations involved in doing the task.

Additionally the changes from 11.3->12 really mean we need to update the guidance/info on a few areas (the ones I'm personally familiar with are replication, special vdevs, vdev removal considerations during pool design, raidz choices, dedup implications, smb, and iscsi, but most users will be affected by at least some of those as they are core uses).

My main need personally is on the spot confirmation of go/no go on writings. Someone I can quickly check "is this kinda thing okay" without needing to go through the formality of raising a jira/github PR as such, and get pretty much same day or at worst next morning turnaround of an answer, who can retarget quickly if not as wanted, who will accept "good enough is good enough for now" and wbo aims to only say no if there's a real technical or structural (writing/topic organisation) issue, that can't be left until after release.
 
Last edited:

ornias

Wizard
Joined
Mar 6, 2020
Messages
1,458
Okey, i;ve started the work on the migration today.

Some updates:
- Sphinx builders for not-officially supported outputs suck.
- I've got all pages outputting in the new format, without looking like crap
- Most auto-generated content has been migrated to the new format (aka hardcoded manually, where needed)
- Some HTML elements need work (mostly some boxes around content, noting major)
- in-text icons need work (aka replacement), as those where implemented using some not-so-clever hacks.

The PoC/WIP PR by friday is still on-track. :)
 

ornias

Wizard
Joined
Mar 6, 2020
Messages
1,458
Addendum:
I started really digging through the new manual system and I figured out whats wrong.

Most of the old content is actually already ported, but one couldn't find it because om IDIOT designed the menu and sorting. (really, it's like IX let a blind person design the sorting).

How to design a good menu:
1. No more than 3 branches deep
2. Don't add needless clickthrough pages that create needless extra branches in the structure
3. Just like the GUI: Sort by function, not by goal primarily (one getting started page is fine) (basically means: follow the application GUI)
4. DONT put oversized "tags" above the sub-menu for in-page content! (one only sees tags now, not the most important menu)
5. Spacing branches in a menu needs to be RELATIVE to the fontsize. This spacing is not enough with this oversized font
6. Make clear which menu item is a branch and which are the leaves. Thats currently done with a less-fat font, but this is not enough. The current "50 shades of gray" used to differentiate menu items is not clear enough
7. Keep OVERSIGHT on the sorting. Directory services are NOT a "getting started" item. Period.
8. Think about titles, "TrueNAS solutions" lists everything EXCEPT TrueNAS Solutions. These are "External Solutions" or "Addons"
9. What is that "SCALE" reference doing there. This needs to go. Put it under a "developerment" branch with all other dev shizzle.
10. I literally got migrate attacks from looking at the menu. Seriesuly, see above.

To be frank: With this quadrillion of needless clickthrough branches I don't think I want to continue porting anything. I would first be required to completely overhaul this, monstrosity.

While originally being mild, i'm going to take a different stance now after having worked on this:
@Kris Moore and @morganL :

You are about to release an enterprise product and this manual is not acceptable enterprise quality. Not because of content missing, but the terrible design. Pull the UI team for a day, SERIEUSLY.

*Edit*
Look at how Hugo themselves did their manual menu:

If you do this and just reshuffle a few things, you would have an amazing manual!

*edit 2*
It seems you guys used docsy as a template, without looking how docsy themselves use it:
No more than ONE(!) expandable menu item, before it gets ugly.

The primary thing:
- If you don't have a page behind a dropdown, use a team which supports "Dropdown-only" menu items (don't use click-through pages)
- Don't go more than 1 dropdown deep, unless the theme as clear support for it
 
Last edited:

Kris Moore

SVP of Engineering
Administrator
Moderator
iXsystems
Joined
Nov 12, 2015
Messages
1,448
I guess it would be helpful to stop and clarify goals here. To be clear, the new docs design is not intended to be a top-to-bottom type user-manual as before. All 380+ pages of it. It is designed to be more topical in nature, which will let us also link more effectively from pages in the UI to specific HowTo style tasks.

Reading your response here, I'd say the biggest challenge you seem to have is the nested menu / sections, but you also have good points about the tag cloud being higher up than the ToC for a specific page. That seems like an easy fix. I'll share this with the docs folks and see what we can come up with.
 

ornias

Wizard
Joined
Mar 6, 2020
Messages
1,458
To be clear, the new docs design is not intended to be a top-to-bottom type user-manual as before.
Sure, but things still needs to be... well findable without UI references.

Reading your response here, I'd say the biggest challenge you seem to have is the nested menu / sections.
Yeah, preciesly, that one looks like it has been designed by someone without design experience

I'll share this with the docs folks and see what we can come up with.
Wait, You let a user facing design be made by a docs team? Thats... Weird.
But it does explain the beginner mistakes.
 

Stilez

Guru
Joined
Apr 8, 2016
Messages
529
I guess it would be helpful to stop and clarify goals here. To be clear, the new docs design is not intended to be a top-to-bottom type user-manual as before. All 380+ pages of it. It is designed to be more topical in nature, which will let us also link more effectively from pages in the UI to specific HowTo style tasks.
That's all kinds of alarm bells.
  • From 12+ a detailed manual is not going to be produced.
  • Instead vague "topics" will be covered ("more topical in nature")
Kris, this notion just doesn't feel like its going to fly. Your vague topics in fact *need* that detail. Like I said before, to just create a pool, you need to understand what the options in the UI mean, and the main implications of choosing different options. You seriously cannot tell someone that to create a pool, use this Web UI page, with options included, but omit totally critical information about the included options the form requires them to select from. To pick a few examples from the most basic task:
  • To create any pool you need to understand the controls in the UI for pool creation. That detail isn't provided.
  • To create any pool you need to be told basics such as "you won't be able to remove a vdev in future, if you did your pool THESE ways, only if you did it THOSE ways," before you commit to a specific design believing you can redo it later.
  • To create any pool, you will be asked to choose compression, permissions, whether or not dedup, which dedup algorithm, whether or not encryption, what kinds of choices for these. Which means understanding the implications of those options.You can't just say "well you shouldn't use that option, then". The options are provided, users will expect to be told how on earth to use them properly.
Your vague notion of "being more.topical" or "task focused", and "not covering" top to bottom - will it, or will it not, actually tell users how to configure and use their NAS? Because from here, this starts to feel more like a copout, where users won't get that information any more. Even if they paid for the product.

Instead they will get "topical" and "task" oriented material, but those pages either do, or do not, link to the detail of how to configure and make choices about their NAS.
  • If they do, then you are effectively keeping the full original docs, just reorganising them. (Same scope and information, and updated for v12, just not in long pages). That's fine, just confirm that's okay and its good. Then all we are discussing is semantics.
  • But if they don't, then please, what exactly the heck are users (included your paying and enterprise users) expected to do, when they come to TrueNAS #101, basic tasks like "create a pool" and find that the fields and options in the UI aren't even explained to them enough to understand the choices cogently?
The problem really is that yes, we can agree the 11.3 docs were long. Perhaps reorganising would help in some ways. But there wasn't much that could actually be left out of them. The information was *needed* - not all by one person, but generally by all - to operate the NAS.

I think I need to ask 4 things, from you, to.clarify my confusion:
  1. Do you envisage user guidance becoming dumbed down, or Web UI page options and their very real possible implications/consequences left unexplained? (Never mind how it's *organised*). (Or, put another way, if I have a v12 web UI option, should I be able to find in the docs, what that option does, and the implications of making different selections?)
  2. Regardless of how organised and presented, what if any kind of material in the 11.x guides do you see as being left out of the core 12.x hubs' docs, if any (assuming users don't write informal extra docs)? If its all there ready for v12, then again - semantics and search. If not, what's omitted?
    (Note: "11.3 docs will be in the docs hub" doesn't count: 11.3 docs are sporadically misleading for v12 as it's out of date. They will become more misleading as time passes.)
  3. If the task I'm doing doesn't match one of your conceived tasks, how do you envisage I should find the information about a specific option on the webUI page? (If "search box", have you actually *tried* searching yourself for that sort of info? It almost always isn't there/doesn't work/can't be found that way. See OP. If a different method, then how?)
  4. If I need to use search because it's unclear which "task" or nested-menu item to look under, how is it envisaged that I quickly locate the specific "correct-for-v12.0" or "correct-for-v12.1" information for my current version of TrueNAS, in particular if it's changed since the older v11.x-Ux versions?
 
Last edited:

ornias

Wizard
Joined
Mar 6, 2020
Messages
1,458
I would invite anyone to try and lookup a few topics in this new thing.
Even if it is "topical", that menu is really an unworkable abomination.

To be frankfully honest: The one designing it should never touch UI ever again.
 

Dismayed

Dabbler
Joined
Oct 17, 2015
Messages
33
. . . 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. . .

So what is the point of even writing open source software if there isn't adequate documentation to actually use it?
 
Status
Not open for further replies.
Top