Page 1 of 2

Documentation: Fail

Posted: Thu Dec 27, 2012 9:53 pm
by QuadeHale
I've been using Amahi for a few months now. It's pretty solid, and while some of the bugs are really frustrating, it was definitely easy to set up the way I needed it, and it has tremendous capabilities moving forward.

Unfortunately, the documentation (especially the Wiki) SUCKS. If I had more problems, I would probably go back to WHS - fortunately I'm a bit tenacious.

There are so many references in the wiki and even the forums here that are horrendously outdated. As an example, I'm trying to set up OpenVPN - which was no problem to install on Amahi and the control panel checks out - but the Android page hasn't been properly updated for many months. This is just one example - but there are a metric ton of outdated articles floating around on there. Which is really frustrating, as I feel like you guys are jumping the gun on pushing things like the convenience fees on the apps, while basic functions, like VPN (and being able to ACTUALLY turn off the DHCP server permanently) are so poorly documented it hurts my brain.

If I had more experience with VPN, I would be updating the wikis myself - but I don't, and I honestly have no idea where to start. As a whole, the Wiki really, REALLY needs to be kept better as any googling of major problems I've had lands me there.

If you want to get in to the 100k+ user range quickly, more effort and energy needs to be placed on fixing bugs and on the wiki. You'd spend less time responding to "HERP DERP" posts on the forum if you had a properly functioning wiki!

Just throwing it out there.

Re: Documentation: Fail

Posted: Fri Dec 28, 2012 6:10 am
by cpg

Let's collect the URLs that need updating please and let's make this actionable: OpenVPN for Android? Outdated pages? (which ones?)

The DHCP situation is unfortunately a bug in Ubuntu that is hard to patch for all.
Granted, we had a bug on that way back when, however, we fixed it. Only to re-surface as an upstream bug :(

Your points are well taken, harsh as they are .. now please let's make them actionable :)

About the tone ... Think about this: Microsoft (WHS) is a mega corporation of multi-national reach, with an unbridled monopoly. Amahi cannot yet hire one person full-time to maintain things. Even with the app fees, which are generally modest at best. We are a group of dedicated people and we have to manage constant spammer attacks, maintenance, backups, etc., etc. You get the picture.

Now, things are constantly getting out of date, and the world is moving forward with new version of Android (which we may or may not have access to).

I personally work more on infrastructure and the platform, installer, etc., but I see the team working on the wiki doing a great job, as much as they can keep up. If you can give actionable guidance, we are happy to update the wiki.

That said, you can also update the wiki yourself. Register (needs approval due to MANY spam cases), and we can also help getting you up to speed. I think we have a macro for easily marking pages that are a little bit out of date? I forget myself if we have this, but if not we should.

Anyway, points well taken!

Re: Documentation: Fail

Posted: Fri Dec 28, 2012 6:27 am
by dnfalk
I would be happy to help you through any issues you are having. So far its just the openvpn page in relation to Android? I myself do not have an android device but we can work through any and all issues via IRC if you would like. I am normally accessible there most of the day.

Re: Documentation: Fail

Posted: Fri Dec 28, 2012 8:03 pm
by sgtfoo
Having dated wiki article isn't so bad, but keeping all the articles is also a plus... if some way hasn't worked, then another one might.

If it ain't broke, don't fix it,.. kind of thing.

Perhaps if anything, the main table of contents that leads you into the articles could use a restructuring, but that's up to the Amahi core team. (unless the guys wanna allow any of us "experts" to crack at the TOC.

To be honest, I don't find the wiki to be any bad at all. I know where to go for most answers.

Re: Documentation: Fail

Posted: Fri Dec 28, 2012 8:06 pm
by dnfalk
The hope is that the community will be able to provide documentation for all types of users. Some things are lacking we just need to identify what they are and resolve them.

Re: Documentation: Fail

Posted: Fri Dec 28, 2012 8:31 pm
by cpg
We're open to anything that makes sense. Anyone can propose changes.

The main page is locked because there were so many spammers attacking it.

However, any time we change it, we can start by cloning it, say into NewHomePage (or anything, really).

Then you can edit that at your will ... then we can discuss when you are ready and we swap that one we agree on into the main page.

So, anyone and everyone is welcome to make changes that improve things.

The main page has been evolving and over time has been traditionally become a mess, then we clean it up and then it evolves again to a more messy state.

Is it time to do that again? Would you like to propose concrete changes? Make a clone page and propose!

Re: Documentation: Fail

Posted: Fri Dec 28, 2012 8:46 pm
by sgtfoo
In other communities, I've noticed that the overflow wiki articles that aren't "ideal" solutions for certain tasks around a software piece are left in the "how-to" section of a forum. This may or may not be a good way to separate the less-official or un-tested methods about Amahi away from the more "official" wiki.

We need some analytics of the user-base and wiki pages that Amahi has right now, in order to figure out the more commonly used parts and the most commonly-hit articles. Then it would be mucheasier to sort out the pertinent top-of-page articles from the lesser used ones.

Re: Documentation: Fail

Posted: Sat Dec 29, 2012 5:55 pm
by cpg
Here are some analytics for the wiki since we released ubuntu. ... lytics.png

What does this tell us?

Note: There is a period of about two months not included in this data because the wiki somehow lost the analytics configuration in an update and we did not notice for a while.

Re: Documentation: Fail

Posted: Thu Jan 03, 2013 8:16 pm
by QuadeHale
I'm totally in for helping with the Wiki - is there any way it could be tied to the forum/ login? it might entice more work on the wiki from everyone involved, unless you think it'd just create another spam issue... just a suggestion

but honestly I haven't a clue where to start - sgtfoo brought up working on the "core" pages first, but I am of the opinion that the low-hit pages are really what should be focused on, or even ones that haven't been updated in a while.

Even so - looking at the analytics page, there are a few key topics that "pop out":

-VPN including windows and android
-VNC (there has to be an easy way around this)
-How to handle Greyhole's intricacies.

Here's my problem though: Amahi seems to be "marketed" (as much as you can market a basically free product) with simplicity and power in mind: bringing people over from the Windows world - but none of the articles are conducive to that. Do you guys have a "completely new to Linux AND Amahi" page/wiki?

I've been messing around with linux for a few years now - so most of the wiki doesn't scare me, but if I were to build an Amahi machine and sell it to someone, I'd never be off the phone.

I'd like to tackle the VPN page (especially just to get myself rolling) and make it easier on new users because VPN is so important - do we have somewhere else other than IRC to make this happen?

Re: Documentation: Fail

Posted: Fri Jan 04, 2013 5:44 am
by bigfoot65
Yes it would be nice if it was all SSO, but not sure if that is doable. It does not take long to get an account and you can use the same credentials.

You are headed down the right path in regards of where to start. There are many things that need updating. I do agree we need more basics documented on how to do things with Amahi. Key to remember is the wiki has been developed over time by the Amahi user community. The core team does not have the resources to manage it as we would like. Many contribute, but that is from a snapshot in time. Once they have documented a process, it never gets updated as things change. That's conducive of an open source environment.

It might be worth trying to come up with an outline of what a new user would need. I think that would start with new install or migration from existing server. Then follow with the basics for getting the server rolling, such as VPN, SSH, etc.