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
----------------------------------------------------------------
