topic Re: Detailed Documentation for Alfresco in Alfresco Archive

Detailed Documentation for Alfresco

hramsdell — Fri, 06 Feb 2009 02:17:24 GMT

Hello all,My company has recently started documenting in extensive detail open source systems including Alfresco. We are looking for feedback and suggestions on the types of diagrams, models, metrics, etc. that would be useful to you all as developers of this system. Currently we include a number

Re: Detailed Documentation for Alfresco

mrogers — Fri, 06 Feb 2009 10:10:07 GMT

Just had a quick look at your site, admittedly only the "lite" version since I did not want to sign up for a paid service.

I could only see details about a small part of Alfresco. In fact the system metrics says only 24 files - should be a few thousand!

To be useful your site will have to add detail that is not already available through our IDEs.

Re: Detailed Documentation for Alfresco

hramsdell — Fri, 06 Feb 2009 17:53:12 GMT

I got permission from the higher ups to give out an unrestricted access pass. Feel free to look through the entire documentation set using:

username: guest
password: guest

And thank you very much for taking the time to give honest feedback.

- Howard

Re: Detailed Documentation for Alfresco

mrogers — Fri, 06 Feb 2009 18:31:52 GMT

Thanks for the access.

At the moment there is only the Alfresco SDK on your site which is only a small amount of sample code.

I noticed that your tool was reporting that public static final variables were marked as "unused". Which seems incorrect.

Re: Detailed Documentation for Alfresco

hramsdell — Fri, 06 Feb 2009 18:33:57 GMT

Excellent find I'll open a bug on our side. What would be a better code source for us to use to document all of Alfresco? And can you tell me if this sort of documentation is worthwhile? I don't want to spend a lot of time on a pet project of mine without someone finding some value in it

Again thanks for the feedback!

Re: Detailed Documentation for Alfresco

hramsdell — Mon, 09 Feb 2009 21:36:17 GMT

mrogers - What is the language makeup for alfresco? Is it primarily java or a mixture? Also, where should we be picking up the source for our documentation? We'd like to regenerate with a new baseline to see if we can capture more data. Also an interesting metric that we are working on is "code similarity". This should help with refactorings. I'll check if it will be in the next refresh or not, but it's definately a great way to look at pulling methods out.

Re: Detailed Documentation for Alfresco

mrogers — Mon, 09 Feb 2009 22:53:34 GMT

The normal way of obtaining the alfresco source is via subversion.
svn co svn://svn.alfresco.com/alfresco/HEAD

All the projects are important, but most of all you want the "repository" project.

The primary language is Java, although there is extensive ECMA script, and small scatterings of other languages. We are also rapidly gaining lots of freemarker script.

It would be interesting if you can produce good documentation for the script components since I'm not aware of any tools that manage this.

Also if your tools can make a good job of documenting spring configuration files then I'm sure that would be useful.

I'm waiting to see whether your Java tools add anything above those we already have, but I'm ready to be impressed

Re: Detailed Documentation for Alfresco

hramsdell — Tue, 10 Feb 2009 02:23:06 GMT

We are going to refresh the alfresco documentation based on your input. We'll grab the codebase from the svn repo tonight and you can expect to see a fresh new set of documentation for it tomorrow. Feel free to take a look tomorrow since it's queued for tonights run and see if we got the entire codebase this time.

Thanks!

- Howard

Re: Detailed Documentation for Alfresco

hramsdell — Tue, 10 Feb 2009 04:40:21 GMT

Looks like similarity index didn't make it in this build. Once we get all the branches on ourside merged I'll make sure to get that turned on.