Re: [Plone-docs] Plone 3 Theme Reference Manual

[Marco De V. <sta...@sp...>]

Il 5-03-2008 13:31, A Bowtell ha scritto:

> Hi, I've submitted the Plone 3 Theme Reference Manual for review. I
> wasn't

In 5.2:
-------

> In this case, the template used by the component can be customised
> and will be rewritten so that the image points to header.jpg (in the
> skin layers) rather than a method to create the image tag in a
> browser view.

Upon first reading I had a hard time figuring out what the last part 
meant... my fault because I didn't carefully read the code, but it could 
be helpful IMHO if the paragraph was more detailed, such as: "...so that 
the image tag points directly to header.jpg (in the skin layers) rather 
than using a method to create the whole image tag at runtime in a 
browser view."

In 5.3:
-------

I think the following code excerpt, which is currently at the end of the 
  Skin section, should actually be at the end of the Components section:

> <img src="" tal:attributes="src 
>  context/++resource++dotnet-images/header.jpg" />

-------

I didn't proceed further as you wrote you still need to work on stuff 
after 5.3.

Globally, I think the document is very well written and laid out, 
although I still have the feeling I started to express in my previous 
mail: I, as a user, expect a "reference manual" to tell me everything I 
need to know about its topic, but this rather looks much like a big 
"where is what" reference with lots of useful info and pointers, which 
is, precisely, useful and needed, just not the comprehensive and 
self-sufficient manual one might expect.

Actually, when looking back, this is very well anticipated in the Aims 
section of the Introduction (1.1). Maybe it simply does not fit my idea 
of a "reference manual" :), which at least in part fits with the idea 
described on 
http://plone.org/documentation/tutorial/creating-documentation-for-plone.org/document-types
But I understand we do not have a more suited document type available, 
and this doc is too large to be considered a tutorial.

Please take this just as a constructive comment, maybe giving you some 
hints to rework the intro a bit, because you're doing a very good work! 
I'm eager to read the rest.

-- 
Ciao,
   Marco.