TrueNAS Documentation Plans

[Kris Moore]

In 2020, FreeNAS and TrueNAS were unified and TrueNAS SCALE was born. These were major product changes and required a rethinking of the documentation process to be both more efficient to produce and more comprehensive in their coverage of complex topics.

The FreeNAS and TrueNAS 11.3 documentation (v1.0) was rated well by some users, but our internal metrics were showing that very few people were using the documentation to answer their questions. The FreeNAS community was filling the gap in topics like how to troubleshoot systems and configuring a system for complex scenarios.

We decided it was time to move TrueNAS 12.0 to a modernized infrastructure that allows for users to contribute their expertise in a wider variety of complicated topics. We opted for Hugo and GitHub (TrueNAS Docs 2.0) as the basis for TrueNAS 12.0 documentation. This approach is similar to how Kubernetes is documented and also allows unifying all product documentation, including hardware, SCALE, and TrueCommand documentation, into a single searchable location.

Due to the significant overhaul that was required in 2020, the TrueNAS 12.0 RELEASE docs were incomplete when compared with the TrueNAS 11.3 docs. When website infrastructure and other issues were resolved, the team refocused to bring TrueNAS 12.0-U2 (v2.0) documentation up to parity with TrueNAS 11.3 content and continued to document all the new TrueNAS 12.0 capabilities.

With the new website infrastructure and content parity in place, the team can now return to fully organizing content and preparing for future documentation projects. This v2.1 Documentation Hub project also requires a lot of software! The team has completed most of the additional backend work and is planning to release Docs Hub v2.1 in time for TrueNAS 12.0-U3 (expected in March 2021).

What’s in the new TrueNAS 12.0-U3 Documentation site?
The major changes to the site are going to be:

Simplified Navigation
The left-hand side menu will become more like the menu with TrueNAS. It will be hierarchical and expandable to include all the subtopics. Each of the topics will then have a better organized list of subtopics. It will reflect the actual user interface workflow within TrueNAS better.

Powerful Search
The tag cloud will be removed in favor of a better search engine to help find the right topics. Searches can be done within the context of that version and will find more relevant information than before. All major documentation topics are now included in the search function and can better show TrueNAS CORE, SCALE, iXsystems Hardware, or TrueCommand content.

Version Control
The documentation site will assume that users want to read documentation for different versions/or editions of TrueNAS. Version control will be added and new versions will become clones of previous versions. Many topics will be common between versions.

Enhanced Mobile View
The updated docs site also includes revamped support for browsing on mobile devices. Content is automatically re-formatted, and menu elements hidden when browsing on small screens.

Improved Docs UI Elements
The updated documentation site includes a variety of new pre-built documentation elements, such as tabbed information views, hint boxes and even auto-generated SVG support.

Off-line documentation
The new site will have an ability to create a single HTML view or PDF document of a specific section of the docs site, I.E. TrueNAS CORE documentation. . This can be used to create off-line documentation for a specific release. (WIP Example of Single Document View)

Merger of QA and Documentation
The new documentation infrastructure enables Quality Assurance (QA) engineers, System Engineers, Support Engineers, experienced users and the community as a whole to contribute to the documentation, fix bugs, and add improvements. We’ve merged our Quality Engineering and Documentation teams so that documentation can be tested in parallel with software. We expect this will improve quality, completeness and timeliness going forward.

 

[Samuel Tai]

@Kris Moore, will it be possible to promote highly regarded forum articles, like https://www.truenas.com/community/t...ide-to-not-completely-losing-your-data.12714/, or the SMR drive resource, to first-class members of the official documentation?

 

[Kris Moore]

@Kris Moore, will it be possible to promote highly regarded forum articles, like https://www.truenas.com/community/t...ide-to-not-completely-losing-your-data.12714/, or the SMR drive resource, to first-class members of the official documentation?

I don't really see why not. I'd suggest when the refresh takes shape next month we can then circle back and try to get some of this user-created content reviewed. The cool thing is, its just markdown, so often its just a matter of clicking "edit" on the docs site, and then copy-n-pasting the content directly from the forums. A little cosmetic touches here and there, if necessary, and then its ready to go.

 

[eshutah]

I'm not having any luck with the new "hub" interface. Clicking on the "guide" icon used to take me to a tree that allowed me to eventually find what I was looking for. At the moment I am looking for the documentation for the System/Certificate Authorities/Add/ interface. I typed "Certificate Authority" in the search box and received no results. Then I'm left wondering. Is is covered in "Introducing TrueNAS"? Could be. Is it covered in "Initial setup?" Could be. Is it covered in "Data Sharing?" Sounds likely. "Advanced Management?" "Solution Integration?" "Additional Topics?" I was able to rule out "TrueNAS SCALE" with some degree of confidence. Beyond that, it will apparently require checking each category and hoping for the best.

At this point, I give up and start googling the forums, hoping the pre-12.0-U2 answers will be relevant and/or accurate. I never intended for my life to be dedicated to struggling with FreeNAS/TrueNAS. I thought is would be a tool I set up once, modified occasionally and leave in the background while I work on other projects. Much of the documentation appears to be written by people with 10+ years of NAS/Security/FreeBSD/Network experience for people with 10+ years of experience in the same areas. I have actually been working with computers since the mid-70s and I have dealt with all of these during my career. Well, UNIX instead of FreeBSD. But My knowledge of modern tech vocabulary and systems architecture just isn't there.

I'm not really sure I have much of a point, except that the documentation fails to explain the basics or to offer any insight (links) into how to understand the relevant basics. It is fair that TrueNAS isn't in the business of level 101 primers. But each of these topics is quite in-depth and takes a long time to master. Most often I end up cutting and pasting from examples other users have posted, which isn't the same as really learning why they did what they did.

 

[Kris Moore]

I'm not having any luck with the new "hub" interface. Clicking on the "guide" icon used to take me to a tree that allowed me to eventually find what I was looking for. At the moment I am looking for the documentation for the System/Certificate Authorities/Add/ interface. I typed "Certificate Authority" in the search box and received no results. Then I'm left wondering. Is is covered in "Introducing TrueNAS"? Could be. Is it covered in "Initial setup?" Could be. Is it covered in "Data Sharing?" Sounds likely. "Advanced Management?" "Solution Integration?" "Additional Topics?" I was able to rule out "TrueNAS SCALE" with some degree of confidence. Beyond that, it will apparently require checking each category and hoping for the best.

At this point, I give up and start googling the forums, hoping the pre-12.0-U2 answers will be relevant and/or accurate. I never intended for my life to be dedicated to struggling with FreeNAS/TrueNAS. I thought is would be a tool I set up once, modified occasionally and leave in the background while I work on other projects. Much of the documentation appears to be written by people with 10+ years of NAS/Security/FreeBSD/Network experience for people with 10+ years of experience in the same areas. I have actually been working with computers since the mid-70s and I have dealt with all of these during my career. Well, UNIX instead of FreeBSD. But My knowledge of modern tech vocabulary and systems architecture just isn't there.

I'm not really sure I have much of a point, except that the documentation fails to explain the basics or to offer any insight (links) into how to understand the relevant basics. It is fair that TrueNAS isn't in the business of level 101 primers. But each of these topics is quite in-depth and takes a long time to master. Most often I end up cutting and pasting from examples other users have posted, which isn't the same as really learning why they did what they did.

Hang tight, this is one of the big things that this re-org / refresh of the content is intended to help alleviate. Appreciate the feedback though!

 

[eshutah]

Thank you for responding and acknowledging responding! On a different topic, where do find the threads for "Feature Request?"

-Evan

 

[Kris Moore]

Feature requests usually end up as "Suggestion" tickets on jira.ixsystems.com. After they get some votes from the community, we evaluate and then see if it can bring it to the roadmap.

 

[Stilez]

I have two suggestions at this point. The first of which I've already mentioned on Slack.

1) Make clear it's beta or work in progress

By 12.0-U3, docs will have undergone 2 major revolutions in 6 months. Doubtless the community will have input but cant really give it till we see the U3 docs as released. At which point there will still be potential for important community-originated observations of issues and shortfalls, because it would be incredible to spot everything important in the last while. So my first point is expectation management - EITHER release the U3 docs site as a beta OR release it with a header note saying it's still a work in progress.

Because the very last thing you want is to release it looking like it's supposed to be final, and have significant changes based on post-release community observations. It must not look like docs are unstable - and 3 major changes in 8 months will inevitably look like that.

Also because until U3 docs comes out in beta/prerelease/test, the community can't really help by contributing or commenting. So assume all feedback will be post U3. Hence indeed beta/WIP. For example, we may have ideas about section organisation, version handling, or search - but if we do, we can'tr suggest them till we see the site's current reworked version at U3.

So either state its a beta, or state its a work in progress - no harm done, but forestalls that issue for zero cost. Expectation management and clarity. No cost, good benefits.


2) Provide an attractive feedback form on all docs pages

A major source of docs feedback will be users who look for help and don't find it, or find what's there is confusing or pitched wrongly. It's also the only way you'll find 95% of docs issues because most people won't post it on JIRA or the forum.

So I think it's crucial to have a form under the docs, like on some other docs sites: "Didn't find what the help you needed? Tell us what you're looking for. Optionally also leave an email address so we can tell you when this page is updated". Make it sound like it really will be paid attention to ("Most of our docs updates come from feedback from users like you! Please tell us if this page needs to be improved."), not just a blah text box. And a short script that collates feedback somehow - maybe some kind of github table that indexes page -> list of feedbacks & dates. So we can remove dud/non actionable/fixed comments, and any user in the community can see clearly what feedback existed on pages.

 

[Stilez]

The FreeNAS and TrueNAS 11.3 documentation (v1.0) was rated well by some users, but our internal metrics were showing that very few people were using the documentation to answer their questions.

Actually, Kris, this was key info that I don't think came out at the time. curious how you measure that. For example, I'm sure when I used the docs, it didnt show up on any metrics. How was success/failure captured or estimated?

Whether or not it did (I could be wrong), its helpful for understanding.... thanks!

 

[eshutah]

A major source of docs feedback will be users who look for help and don't find it, or find what's there is confusing or pitched wrongly. It's also the only way you'll find 95% of docs issues because most people won't post it on JIRA or the forum.

As this thread's token newbie, I have been burned by this. In hindsight it makes sense that the "developer" ecosystem (jira) is separate from the user community based portal. At some point in my early days of FreeNAS, I googled something and ended up on the jira site. I had never heard of jira before, and I didn't notice the exact name of the web site at the time anyway. I found some helpful information and later tried to find my way back. At that point I kept ending up on the community side of things, never finding the prior response or the tell-tale screen format.

As far as accessing the TrueNAS web pages goes - I guess I expected there to be a common login from a single web page, from which you may choose to make an informed choice about which way to go. But now that I'm playing with TrueNAS, Windows 10, PowerShell, Raspberry Pi Debian, FreeBSD and Arduino, I should be more expectant of diverging user interface designs. Even things like "cut" and "paste" can be a pain in the ass to keep track of on a per screen window basis.

How well do you know your user base? I ask because if all of your users are, say Cisco veterans, using Cisco-style documentation would make sense. If they are all Python programmers, a whole different layout would make sense.

Thank you guys for all of the hard work. I don't miss my software developer days when the only time anyone thought about you was when something wasn't working.