Really good documenation will be key to success.

[Soid]

This is more of a documentation request then a feature request. I'm probably the target market for HexOS. I'm willing to do a little bit of work to get it working, but not super interested in spending a lot of time tinkering with it once it's going. For me it's a tool to accomplish a task, and the less time I spend tinkering, the better. So I'd like to offer my insight what I think HexOS will need to succeed.

I think HexOS will not succeed in their presumed goal of capturing the consumer / small business market without good documentation for the layman . I find that the best technical products out there aren't necessarily the most feature rich, slick, or technically proficient, but really the best documented. I can't count the number of times I've dropped really powerful and supposedly good software just because I didn't know what all that stuff was for and there was too much friction in finding out. It's the reason why I haven't tried TrueNAS until HexOS came out.

That means that every button and every feature should have a tooltip that tells me what it is, and a hyperlink to the related help file to learn more. I should never be left to wonder what a random pictogram is supposed to mean or do, what an abbreviation means, what a setting does, or what is or is not important.

It also means having really robust documentation. That doesn't mean being the most accurate or having the most detail, but figuring out what people want to do, and showing them how to do it. When I can search for "how do I do X," and I have a clear explanation for how to do it on a piece of software, that's the software I use.

It'd be nice if there was a repository of guides (either written by the HexOS team, or links to known good information) for best practices for various use cases for a NAS.

For context, I set up my synology NAS years ago, and the marketing gave the impression that would be easy and it would just work. Then I got into and it was a bit more involved than expected. I was overwhelmed by all the random jargon and settings I didn't understand. I got tired of googling things, and I only ever got to "well, it kinda works well enough". Instead of being something I was happy to have it became a thing did the job well enough, but I was always dissatisfied with. In my ignorance I probably didn't set things up quite right in the first place, and fast forward 7 years and it has depreciated into an unreliable backup with a lot of disarray and wasted space. Now I'm too scared to try to fix it (hence starting from scratch on HexOS). I'm sure a  lot of my problems are user error, so documentation to prevent such user errors would be greatly appreciated and would protect the burgeoning reputation of HexOS. You don't want people to have a negative experience, even if it's their own fault. As it goes with customers; even if it's my fault, it's your fault.

Some thoughts on what types of documentation could be created:

- An idiot's guide for setting up a network drive in windows / mac with HexOS. Making sure it's properly configured with best practices for permissions, file sharing, and making sure windows always finds it (something I've always struggled with on my synology... *sigh*). Differences in configuration if you're going to be the only user vs multiple users.

- An idiot's guide for configuring a windows / mac backup to a HexOS NAS, with best practices for efficient, safe, and effective backups, and avoiding conflicts with other functions and messy data.  Explain what the backups do and do not do.

- An idiot's guide to self-hosted cloud mirror or cloud drive (like dropbox / Synology Drive) on the HexOS NAS.

- Guides for setting up Plex, Home Assistant, etc, apps within the HexOS environment.

- Guides could include:

• Best practices for backups. How to structure your actual computer filing system and backup settings to simplify backup, and to make sure you're backing up everything you need to, nothing you don't, and how to keep the filing system on the NAS clean. How to clean up my mess and prevent it from turning into a bigger mess.
• Best practices for efficient space usage in backups. Avoiding unnecessary file duplication etc.
• Best practices for accounts, and keeping data separated.
• Helping make sure I don't make a mess when I start layering on, or removing, various apps and functions.
• Other neat things that I didn't know it could do
• Common fixes for common mistakes.
• Showing me how to set it up so that other users in my household / business can use it and its functions without knowing anything about the NAS itself and can focus on just using it.

The ideal outcome from your documentation should be that a user determines they want to do something, they find a way through the documentation, and then they feel smart for having achieved their goal. Or they discover a new function they didn't know they wanted, and feel clever for setting it up. This level of documentation is not a trivial task, and it will probably mean finding and hiring specialized technical communicators. Some software has the advantage of a dedicated user-base to do that documenting for them, but HexOS doesn't have that advantage. So you'll have to create that knowledge and facilitate users to create that knowledge.

 

[Kurma]

I second that, documentation is really important

[Soid]

I hope it didn't come off that I was complaining about the current state of documentation. It's Beta, so of course it's going to be light on documentation.

I'm already pleased to see the seeds of some of the features I was discussing. Such as, after making a folder, when you click the "browse" button it provides a simple to follow explanation of how to map the drive. There are (?) buttons next to basically everything, and though they are dead, it shows the intent is already there. Once I got into the dashboard and started actually poking around, it took no time at all to get folder set up, the drive mapped, and a new backup going from by PC. Big thumbs up.

[jonp]

This warrants further comment but just wanted you to know it's been seen and we fully acknowledge this need. 

[Declared2727]

On 12/12/2024 at 3:05 AM, Soid said:

I hope it didn't come off that I was complaining about the current state of documentation. It's Beta, so of course it's going to be light on documentation.

I'm already pleased to see the seeds of some of the features I was discussing. Such as, after making a folder, when you click the "browse" button it provides a simple to follow explanation of how to map the drive. There are (?) buttons next to basically everything, and though they are dead, it shows the intent is already there. Once I got into the dashboard and started actually poking around, it took no time at all to get folder set up, the drive mapped, and a new backup going from by PC. Big thumbs up.

I don't see this as complaining, it's important for the Beta testers to identify what's going to make the product work for them. As someone without any programming or IT background, I still end up being the "fix-it" guy at work. Good documentation (Excel, I'm looking at you here; so easy to lookup "how to do X") has made that role actually possible for me, especially when trying to troubleshoot something that seems obvious, but isn't working.

[FangerZero]

I think how to use from a mac/windows perspective is great. Like accessing the actual NAS portion a normal person may not know how to do that. I do since I've done a lot of networking with windows sharing in the past.