Hi David
Yes, I saw some of your posts and I'd like to take the opportunity to
thank you for them, because you saved me time digging through the
source code.
Correct, if in minimum the javadoc would be commented that would be
very helpful.
With Java Frameworks I am used to learn "how to do", but with this
great CMS, my new issues are "which is the best practice". There
usually are several ways to come to a solution. I lose a lot of time
figuring out the best practice, because I need to first find out what
is doable and where does which path bump into walls. The benefit of
this work is reflected in the Magnolia Training. We can not only show
what is best practice, but what you should avoid to not run into dead-
ends. And in addition you will realize how easy and scalable Magnolia
is, if you just would some practical examples.
To conclude: Don't be worried about Magnolia! There is hardly anything
you can not do! So there is also some benefit in having to "reverse
engineer" the code :-)
R&D does a tremendous job in fixing issues found during project
implementation. So at the end of the day "documentation is relative".
I prefer R&D puts there efforts in perfectioning the product and I
will still keep on dreaming of a nice and complete documentation :-)
/giancarlo
On Feb 8, 2008, at 8:27 AM, David Smith wrote:
Hi Giancarlo
I'm a developer and I admit writing end user docs is hard and
sometimes painful. However, I do at least write javadocs if for no
other reason than so I can figure out what the heck I was thinking 6
months ago when I last visited a chunk of code. There are large
segments of the Magnolia API w/ barely more than a couple of words
in the javadocs. That's hardly useful.
I'm not asking the core team to write full docs -- just provide the
scribbles on a napkin they used in designing it. I am more than
technically capable enough to translate and help fill in the
documentation void.
I *love* the product -- just wish I didn't need to reverse engineer
the source code so much to figure out what kind of best practices
the developers had in mind or what interfaces were meant to be used
by implementors.
--David
Giancarlo Berner wrote:
Hi Sena and the rest of the Magnolia world
I have been dealing with Magnolia since it's beginning, but also
with software manufacturers within the last 25 years. I noticed
two things during all that time:
1) Teckies want to write code and hug the product. They HATE
writing documentation.
2) If a Tecky writes documentation, you usually don't understand
it.... If a non-tecky writes it, all important parts will be
missing...
So please don't point your finger on the Magnolia team :-) They
are aware of the lack of documentation, but on the other hand we
all prefer they spend there time making a great product brilliant,
that's were they are experts in. Writing good documentation is a
lot more difficult then most of you can imagine.
What many might not know: There is a 4 day, comprehensive Magnolia
Developer Training. There are a lot of useful exercises (e.g.
Image Processing, custom modules, detailed repository browser,
etc.), which reflect many aspects we encounter in our project
work. Developers who have taken the class usually have all they
need to work on their projects, including a comprehensive exercise
guide with about 30 step- by-step exercises.
Sena, I can unfortunately not commit to answer all your questions,
but I can try to help you every once and then (or give you some
pointers). You can reach me at gberner [at] xumak [dot] com
Cheers
Giancarlo
On Feb 8, 2008, at 3:27 AM, Sena Gbeckor-Kove wrote:
Hi Guys,
Sorry to butt in on this conversation but I'd like to add my 4
cents and an offer of some help.
I used Magnolia for a company site round about version 2. I've
been watching it for a while an I had all but chosen the open
source version to implement a small CMS for a client. This site
needs to be live and tested by the UK Budget on the 12th of
March, its for a large Management Consultancy. Unfortunately the
docs for version 3.5 CE don't really tell me how to use the
system at all. Is there a getting started somewhere I haven't
found?
If somebody can commit to being able to answer my questions
quickly, I'll happily document everything I have to do over the
next 4 weeks on my blog and the Wiki. I was blown away by v2, 3.5
looks like its probably awesome but I don't know as I haven't
managed to get going with it yet.
Thanks
Sena
On 7 Feb 2008, at 14:38, Will Scheidegger wrote:
Hi again
I noticed that I don't have your Mail address. So: Sorry for
abusing this list. My JIRA username is "will" (what a
coincidence). Thanks for giving me write permissions on the wiki.
Again: Please let me know if we can help in any additional ways
than just trying to structure the Wiki. I'll have a look at the
pages and will post a structure proposal to the list _before_ I
start messing around. But don't expect this to happen in the next
5 days since we're moving our office to a new location on
monday :-/
Cheers,
Will
On 07.02.2008, at 14:28, Grégory Joseph wrote:
Will,
In the new wiki you can *actually* have that structure by
changing a page's parent. You don't have to maintain some fake
table of contents anymore. We also started *tagging* some pages
with version number or other tags, which is another interesting
to find stuff out. The search engine is probably considerably
better than the old one too.
So yeah, feel free to move pages around like you suggest,
that'd be great.
Also, the new wiki has a nice rss feed builder, which should
help everyone keeping up-to-date with what's going on on the
wiki, in their specific fields of interest or on the whole
site :)
FYI, API docs are now published here:
http://dev.magnolia.info/ref/latest/apidocs/index.html
This wasn't said before just because it will be linked from the
new docu website, but as this is being later than originally
thought, well, here goes.
-g
On Feb 7, 2008, at 14:12 , Will Scheidegger wrote:
Hi Greg
Thanks for the reply. I'm a bit less worried as before ;-)
I'll ping you with my JIRA UN and will probably start with
documenting what I have learned so far about the data module.
Still, would it be possible to structure the WIKI a bit? e.g.
- Mag 2.x
- Mag 3.0.x
- Mag 3.5.x
- Configuration
- Templating Tricks & Tips
- Other...
- ...big...
- topics.
The last WIKI did have some structure to it.
Regards,
Will
On 07.02.2008, at 14:01, Grégory Joseph wrote:
Will,
Thanks for the email.
A quick reply:
- we're actually working on a new documentation site which
will be hopefully be better managed than the current one,
and improved on more regularly. We realized a while ago our
documentation was terrible, but as you certainly now, we are
a very small team, so this always slipped under pressure of
larger projects.
- the new wiki is not messier than the previous, since said
previous one had no structure at all either. Maybe the mess
there was just less *visible*. As you have noted, we're
waiting for a license issue to be resolved, so in the
meantime I can only add permissions to specific users. Ping
me with your Jira username and I'll be glad to add you.
- what exactly is your issue with the ACLs for URLs ? Nothing
has been "completely modified", the only thing that changed
afaik is the fact that we moved (un)securedURIs configuration
to full blown ACLs for URLs. We don't always have time to
reply to all user-list emails, so your questions might have
been left unanswered, and I'm sorry for that, however I don't
believe this specific feature is a reason for being worried;
it should only make your life easier, esp. if you use roles
and groups.
As for your questions, I can't promise immediate reactions if
you contact me privately. The users list should be a good
place for this, but as I've said before, we can't always
follow up at the moment either. You can also find some of us,
sometimes, on irc.freenode.net at #magnolia.
The best would probably be to use the wiki. With your
approval, we could then lift content out of it and in the
proper documentation site.
Thanks for the positive and constructive remarks. Your help
is much appreciated.
Cheers,
-greg
On Feb 7, 2008, at 13:40 , Will Scheidegger wrote:
Dear Magnolians
Am I the only one that is a bit worried about the state of
Magnolia?
While the development work that we see is fabulous, the
documentation lags _far_ behind.
- Did you know, that a new tag library was introduced with
Magnolia 3.5? I'm sure it does slick things, but we will
never find out about them unless we trip over them by
accident.
- By know you probably have heard, that the access control
to pages/URLs has bin completely modified in 3.5 - but do
you know how things really work?
- When you visit documentation.magnolia.info it tells you
that the current release is 3.0, also the API linked there
is the one from 3.0. The last update seems to be from May
25th.
- The new Wiki is a mess. It has no structure at all so it
is nearly impossible to browse through articles to find out
what is documented and what not. On top of that "hopefully
we receive a license in the next week" has been greeting us
from the front page for a month now.
MY GOAL IS NOT BASHING THE MAGNOLIA TEAM. As I said: They
are doing a terrific job developing Magnolia. I just wanted
to emphasize that not investing in documentation will not
help at all in the long run.
As I said before on- and off-list: I am more than happy to
help documenting things. But I would need the following
before I get started:
- Specific task: What should I document, what is taken care
of by others?
- Contact: Who can I contact when I have questions?
- Place + access: Where should I document + how? Wiki,
documentation.magnolia.info, other?
The Magnolia developer have delivered the basis for blowing
away other CMS - if we don't deliver the missing
documentation to it, the world will not be able to honor the
hard work of the developers!
Amen!
And now... back to work.
Cheers,
Will
----------------------------------------------------------------
for list details see
http://documentation.magnolia.info/docs/en/editor/
stayupdated.html
----------------------------------------------------------------
----------------------------------------------------------------
for list details see
http://documentation.magnolia.info/docs/en/editor/stayupdated.html
----------------------------------------------------------------
----------------------------------------------------------------
for list details see
http://documentation.magnolia.info/docs/en/editor/
stayupdated.html
----------------------------------------------------------------
----------------------------------------------------------------
for list details see
http://documentation.magnolia.info/docs/en/editor/stayupdated.html
----------------------------------------------------------------
----------------------------------------------------------------
for list details see
http://documentation.magnolia.info/docs/en/editor/stayupdated.html
----------------------------------------------------------------
----------------------------------------------------------------
for list details see
http://documentation.magnolia.info/docs/en/editor/stayupdated.html
----------------------------------------------------------------
----------------------------------------------------------------
for list details see
http://documentation.magnolia.info/docs/en/editor/stayupdated.html
----------------------------------------------------------------
----------------------------------------------------------------
for list details see
http://documentation.magnolia.info/docs/en/editor/stayupdated.html
----------------------------------------------------------------
----------------------------------------------------------------
for list details see
http://documentation.magnolia.info/docs/en/editor/stayupdated.html
----------------------------------------------------------------
