- Joined
- May 28, 2011
- Messages
- 10,994
I'm pretty sure iXsystems has at least one already on payroll but you never know, maybe they have the need for someone. I think it's great that you are looking to keep your wife happy and engaged.
-
Important Announcement for The TrueNAS Community.
The TrueNAS Community has now been moved. This forum will now become READ-ONLY for historical purposes. Please feel free to join us on the new TrueNAS Community Forums
SOLVED TrueNAS 12 docs in awful condition compared to 11.3 - can't IX do something?
- Thread starter Stilez
- Start date
- Status
I like the idea of a flow chart and a a guide on how to report issues to the forum. In other words initial focus is on a methodology and a way of engaging all the expertise in the community forum. We are a slow AI engine....with thousands of years of Human Learning
From the flow chart you could then have specific docs that discuss how to diagnose drive issues or RAM issues etc. these docs can be improved over time.
A reporting template approach often seems to get good compliance - one with slots for the user to put specific information, and report if they did certain tests. I'd perhaps do it this way:
- Make it driven from the web UI, with an online version in case the UI is inaccessible
- Web UI is wizard style, asks key questions, compiles a report, and asks the user to download it and attach it to their forum post.
- This means it can also interrogate the platform itself, to automate answers on the basic hardware, system, VM/jails, and pool structures, which can be presented as a text area and the user asked to blank anything sensitive. (Logs are useful but very hard to isolate private data, so automated inclusion is not suitable for forum help)
The troubleshooter takes the user through a bunch of standard questions, it acts more as a collator than an AI. We don't need to.ask about hardware or software, or enabled services, since the report gathers that data - we only need to ask the user to review and edit for privacy.
- Introduction:
- "Welcome to the TrueNAS troubleshooter. This component will ask questions and collect basic information that can be useful if you need to request help. It may suggest actions to try, or provide a report that can be attached to a forum post, as a good starting point for requesting help from the community or ixSystems support."
- "All information collected is private. If a report.is created, you will have an opportunity to remove any sensitive information before deciding whether to share it."
- Type of problem:
- Is the problem 1) hardware, 2) software, 3) initial install, 4) suggestion for improvement, or 5) not sure/other?
- Appropriate followup questions -
If hardware: disk, ram, boot, network, cpu, not sure/other.
If software: boot, TrueNAS error, pool data issues, VM/jail issue, client ability to use or connect, networking, administration, not sure/other - Problem details:
- What is the problem?
- Is this a new or recent problem?
- When did the problem start?
- Did the problem seem to start after anything changed?
- What do you have to do, to reproduce the problem (make it happen)?
- Does the problem occur every time? If not, when does it seem to happen?
- What have you tried so far, to solve the problem?
- What is the effect of the issue:
- Choose one of these:
Entire platform won't work or unreliable. Platform seems to work but won't boot. Platform boots but can't access user interface/console. Platform UI can be reached but errors occur, or specific features don't work as expected. Platform works but data or storage corruption/risk. Platform works correctly but network clients, VMs or jails aren't working or connecting as expected. Other. - Basic troubleshooting report:
- Do you want to create a basic system summary to include with your report. You will be able to review this and remove any private information before using it?
- If yes:
Creates basic system summary - HW, SW, VM/jails, services, ZFS structures, SMART, and dumps it in a textarea for the user to review and "ok". It'll be added to the report. - About you:
- How would you describe your technical ability and experience?
- Reporting/wrapup:
- "The troubleshooter has identified the articles listed below, that may be relevant.
- "You can download a report of this issue, based on your answers, which may help if you need to seek help."
- "You can read next, about the different ways to obtain support, and when these are likely to be appropriate. These include asking the community for help with an issue, obtaining professional support from ixSystems, or reporting a bug or suggestion if you are sure that this is the issue."
(List of links to troubleshooting articles with matching tags to those the troubleshooter thinks relevant, or something)
(Links to articles: "How to obtain community and professional support" "How to report a confirmed bug or suggestion")
Last edited:
- Joined
- Nov 12, 2015
- Messages
- 1,471
That does sound like a very interesting idea for a troubleshooting / reporting wizard, but also a big project in and of itself :)
I'd suggest tossing that into a Jira suggestion ticket, so we can get some upvotes and monitor how desirable it is to see about tossing it on the schedule at some later date. Don't want it to get lost on page 9 of a very long forum thread.
Kris, this is about a troubleshooter document... not a wizard in the software. I agree we should probably close this thread and start another.
- Joined
- Nov 12, 2015
- Messages
- 1,471
Yep, that was understood. Wasn't thinking of something inside the software UI, but another type of stand-alone doc / wizard. But we still want to track the idea as a suggestion and gauge support and Jira is still the best place to do that so it doesn't get lost. We use suggestion tickets for other things beyond just software changes, including docs, website, portal, etc.
ornias
Wizard
- Joined
- Mar 6, 2020
- Messages
- 1,458
@Pierce For payed technical positions, it's always worthwhile sending a PB to @Kris Moore and/or @morganL
If someone has interesting skills it's always worthwhile having a talk :)
If someone has interesting skills it's always worthwhile having a talk :)
Jon Rosebaugh
Cadet
- Joined
- Apr 5, 2015
- Messages
- 7
In my experience, it is usually the job of the software maintainer to tell the user what the user ought to know before upgrading, rather than the other way around.
If nothing else, I would recommend you focus on a doc about what did change between 11.3 and 12.0; this will be of service to those people who feel the need to consult the 11.3 documentation.
I agree with the topic.
Especially the documentation is even not in the correct order.
For example, it lists quotas before actually showing the chapter with setting up the storage pool.
www.truenas.com
That doesn't make much sense.
Especially the documentation is even not in the correct order.
For example, it lists quotas before actually showing the chapter with setting up the storage pool.
Getting Started
This configuration guide provides step-by-step tutorials for installing and setting up TrueNAS CORE.
That doesn't make much sense.
D
DeletedUser67652
Guest
Especially the documentation is even not in the correct order.
For example, it lists quotas before actually showing the chapter with setting up the storage pool.
That doesn't make much sense.Getting Started
This configuration guide provides step-by-step tutorials for installing and setting up TrueNAS CORE.
Thanks for bringing this up, there's a PR to fix it.
There is one more problem with the new documentation.
The Documentation has an article for pools, datasets and zvols.
But there is no article that gives an overview and direction or best practice tips when to use a dataset and when to use a zvol.
It also doesn't give some suggestions how datasets should be arranged and when someone should nest datasets and zvols in a top level dataset.
For what i have found out so far is the following:
1. It makes sense to create one top level dataset. This makes the task to create Snapshots, Replication and Backups easier.
2. Datasets are for file bases storages, like SMB and nfs shares. Zvols are virtual block devices and are required for Virtual Machines or iSCSI devices. It's possible to nest zvols within datasets.
3. zvol need a size that must be given before creating them. The size can be increased later, but not decreased. If you need 100 GB for a VM, you create a 100 GB zvol and these 100 GB get reserved and can't be used for something else outside of that zvol scope. Thus the free space of your pool decreases. That's not the case for datasets, their reserved space can increase when they grow and decreased when files are deleted.
4. For performance reasons zvols should be put on a pool of mirrors, not on raidz[n]. The size of a zvol shouldn't surpass 80 % of the available space of a pool. If the task of a VM is input/output intensive, like a database running on the VM, the pool for the zvol should be based on SSDs. It's possible to mix datasets and zvols. Jails don't need zvol, they work fine with datasets.
These infos should be in the documentation.
If i get something wrong, please correct me.
If you have more information, then add it.
The Documentation has an article for pools, datasets and zvols.
But there is no article that gives an overview and direction or best practice tips when to use a dataset and when to use a zvol.
It also doesn't give some suggestions how datasets should be arranged and when someone should nest datasets and zvols in a top level dataset.
For what i have found out so far is the following:
1. It makes sense to create one top level dataset. This makes the task to create Snapshots, Replication and Backups easier.
2. Datasets are for file bases storages, like SMB and nfs shares. Zvols are virtual block devices and are required for Virtual Machines or iSCSI devices. It's possible to nest zvols within datasets.
3. zvol need a size that must be given before creating them. The size can be increased later, but not decreased. If you need 100 GB for a VM, you create a 100 GB zvol and these 100 GB get reserved and can't be used for something else outside of that zvol scope. Thus the free space of your pool decreases. That's not the case for datasets, their reserved space can increase when they grow and decreased when files are deleted.
4. For performance reasons zvols should be put on a pool of mirrors, not on raidz[n]. The size of a zvol shouldn't surpass 80 % of the available space of a pool. If the task of a VM is input/output intensive, like a database running on the VM, the pool for the zvol should be based on SSDs. It's possible to mix datasets and zvols. Jails don't need zvol, they work fine with datasets.
These infos should be in the documentation.
If i get something wrong, please correct me.
If you have more information, then add it.
Last edited:
Generally true, but there are situations where ZVOLs are put on pools with RAIDZ1/Z2.
This type of comments can be put directly in the documentation pages... or make a direct contribution.
Feel free to do so.
One more thing:
The documentation says in https://www.truenas.com/docs/hub/initial-setup/storage/encryption/#locking-and-unlocking-datasets
That doesn't make much sense to me.
Because, if you need that option, someone does have "mounted" it or is using it in some way.
If that is not the case, that option shouldn't be necessary, because it should unmount without problems.
In my opinion a warning that you can loose data if you use this option, when someone is accessing the dataset in write mode would be a much better text message. And a lot better would be an overview, how that dataset is currently used. This makes it easier for the user to decide.
The documentation says in https://www.truenas.com/docs/hub/initial-setup/storage/encryption/#locking-and-unlocking-datasets
That doesn't make much sense to me.
Because, if you need that option, someone does have "mounted" it or is using it in some way.
If that is not the case, that option shouldn't be necessary, because it should unmount without problems.
In my opinion a warning that you can loose data if you use this option, when someone is accessing the dataset in write mode would be a much better text message. And a lot better would be an overview, how that dataset is currently used. This makes it easier for the user to decide.
This discussion thread has been ongoing since September 2020 - about 5 months.
It’s been very useful and covered a lot of topics, but has become a catch-all for technical documentation topics that deserve their own attention. So, I’m going to summarize, close the thread, and point to better places for future discussion. New forum threads are welcome for specific issues that are not easily addressed.
The primary issues discussed were:
It’s been very useful and covered a lot of topics, but has become a catch-all for technical documentation topics that deserve their own attention. So, I’m going to summarize, close the thread, and point to better places for future discussion. New forum threads are welcome for specific issues that are not easily addressed.
The primary issues discussed were:
Content Equivalence: The TrueNAS 12.0 documentation started off behind the 11.3 docs. After 4 months of effort, the 12.0 docs now have similar content to 11.3 docs plus the new capabilities of 12.0. Any shortcomings with specific content can be fixed by clicking “edit this page” or can be reported by clicking “create an issue” directly in the documentation site.
General Advice and How-tos: This is an ongoing effort that you can help with!. The original goal of the 12.0 docs site was to allow the community to easily contribute this kind of information and we would love your contributions in this general area. Please contribute if you see a hole you can fill.
Ease of Navigation: The 12.0 documentation wasn’t as organized. A reorganization project was started and is planned to be completed in March before 12.0-U3 is released. A forum post on this initiative has been made. The navigation style is similar to the legacy documentation but the contribution tools will remain in place to encourage community contribution.
Off-line Documentation: The 12.0-U3 documentation (future) site will have the ability to create an off-line PDF document by collecting all content in a major section into a single HTML view that can be exported.
Version Control: Less discussed, but just as important, the new documentation will simplify version control and enable documentation for SCALE to be improved. SCALE beta documentation is being planned to begin after the documentation reorganization project is complete, in April and prior to SCALE 21.04.
- Status
