Quantity not quality

[amcginlay]

There seems to be a lot of documentation, it really doesn't gel together very well though unfortunately. Some of the docs are also clearly out of date.

I am trying to set up NTLM pass through authentication for my users however there is conflicting information on how to do this and I am finding the whole thing very irritating

Something that can really make a good project into an _excellent_ project is high quality documentation.. (the consistency and quality of the gentoo handbook is a very good example).  I think the best thing that can be done right now is a complete overhaul of the docs by those who know what they are doing. take everything that currently exists, weed out the rubbish and neaten up everything else! Don't rely on wiki docs but have that as a compliment to the official documentation!

Here is the gentoo handbook as an example of how good documentation should look:

http://www.gentoo.org/doc/en/handbook/handbook-x86.xml

I really hope the situation improves!

[sidi]

How can I vote?. I'm totaly  in agreement wiht this opinion, only Munwar Shariff book  gives a partial well structured documentation. But only  on Web-Client customization.
Anybody knows of any other edited book?.
Thanks.

[loftux]

If you take a look at http://wiki.alfresco.com/wiki/Special:Recentchanges you will see that this is an ongoing effort. The documentation has really improved, I'm sure more can be done so the editors are probably thankful for any specific suggestions.
As for a book, have a look at this blog post by Jeff Potts, http://ecmarchitect.com/archives/2008/04/29/825
//Peter Löfgren

[frank_s]

I'm totally in agreement (unfortunately, voting has ended, otherwise I'd have voted "Yes").

I've tried to configure CAS authentication, and also attempted to integrate MediaWiki with Alfresco. In both instances documentation was either completely missing, incomplete, or - even worse - there were a number of documents giving contradicting information, resulting in a huge amount of wasted time and an immense amount of frustration. This is exacerbated by the fact that all my queries on these topics in the forum went unanswered for weeks.

Granted, to an extent I would expect that from an O/S project, but I haven't seen anything like that in a project this size. It also makes me wonder what the documentation for the Enterprise release looks like…

At the moment, I'm almost regretting picking Alfresco - I'm not quite ready to cut my losses yet, but I'm getting close, and at this point I can't recommend that our company invest in the Enterprise version, at least not with a clear conscience.

A prime example is the MediaWiki Integration page. It is so vague as to be absolutely useless. Here's a sample:

The final job the localSettings.php file does is to retrieve the configuration settings for MediaWiki from the associated wiki space in the repository. Each wiki space has a child object that holds the configuration properties for the associated MediaWiki instance.

I've just spent a day trying to figure out what that means. There are no details as to what the name of this mysterious file is, what format it's supposed to be, and what file type it is (PHP, XML, plainText?).

Sorry if that sounds like a rant, but I'm really tired of spending days trying to figure out details that should take a couple of minutes to look up.

Frank.

[davidd]

The (lack of) coherent documentation seems to me to be Alfresco's single weakest feature at the moment.

It suffers from the classic Open Source problem of code and features being contributed by people who know
how to use what they've written (because they wrote it) but nobody else does.

[frank_s]

Very true. In theory though, Alfresco should be different, since - although Open Source - it is in the fortunate (and unusual) position to have a company behind it that has a commercial interest in providing good quality documentation. But for some reason this isn't happening.
I can't with a clear conscience recommend to my manager to move from the CE to the EE version unless this improves dramatically. That's a shame, since Alfresco has the potential to be a fantastically useful application for us - not only for document management, but for web publishing as well.

But unless there's documentation and a configuration interface to stop people having to fiddle with umpteen XML configuration files (like any other web app has these days), I can't use it to implement new functionality - sadly, at the moment the cost is just too high, in terms of time and effort. 

f.

[steve]

Hi,

Alfresco has made a significant investment in the documentation department, and the results should be coming onstream very soon…
Hopefully any concerns regarding the poor state of documentation will be completely negated.

Steve

[mrojas73]

Hi,

Alfresco has made a significant investment in the documentation department, and the results should be coming onstream very soon…
Hopefully any concerns regarding the poor state of documentation will be completely negated.

Steve

That's great news, we are starting to see changes specially with the release of the stable version.  Good work Alfresco team.

[berend_tty]

I'm new to Alfresco, but the documentation I see does not give great confidence that i'll be able to use it in my project.
Specifically, I'm looking to use the Surf Platform with JSPs. I understand a proper SDK is in the works, so for now im using the SVN source checkout method.

However, if you want to use Surf with JSP templates, it seems one is out of luck. No Documentation on how to achieve this. Zero. Empty Wiki paragraphs.
I googled it till i dropped, didnt find *anything* usable. 

Oh, and the Document Library for the Alfresco Developers Content Site? It doesnt work on Ubuntu FireFox 64 bit. At least it doesnt now. Javascript warnings, Css warnings and errors. I'm pretty disappointed.