documentation - new titles of examples + list of examples

[Tomek Kaczanowski]

Hi,

I've a suggestion regarding examples included in documentation.

Downsides of current approach:
  a) uninformative titles of examples ("build.gradle", "Output of gradle -q
hello")
  b) because of this there is no way to create "list of examples" (because we
have ~50 examples with the same title - "build.gradle")
  c) numbers of examples suggest that outputs are separate from sourcefile
which is rarely true

Please take a look at attached picture to see how the new proposal differs.
The picture presents the idea - there is still room for visual improvements
via CSS etc.

Upsides of proposed approach:
  a) titles are meaningful, and you can choose them as you like
  b) it is possible to create a useful list of examples (yes !)
  c) sourcefile and output are grouped together which is more logical
  d) the new code is backward-compatible - if you don't add a title, you will
get the filename (i.e. "build.gradle") as title.

Downsides of proposed approach:
  a) someone has to add titles for all examples (not necessarily - keep on
reading)

I have written a patch that does all of it. The only change for documentation
creators, is that you will be kindly asked to add a new attribute to sample
tag - "title". But  as I said previously - you don't have to. For example:
        <sample id="upper" dir="userguide/tutorial/upper" title="Simple Gradle
tasks">
            <sourcefile file="build.gradle"/>
            <output args="-q upper"/>
        </sample>

I wanted to ask you if you like this idea. Any suggestions on how to make it
better ?

--
best regards
Tomek Kaczanowski
http://kaczanowscy.pl/tomek



---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email

[hdockter]

On May 27, 2009, at 11:04 PM, tkaczano@... wrote:

> Hi,
>
> I've a suggestion regarding examples included in documentation.
>
> Downsides of current approach:
>  a) uninformative titles of examples ("build.gradle", "Output of  
> gradle -q
> hello")
>  b) because of this there is no way to create "list of  
> examples" (because we
> have ~50 examples with the same title - "build.gradle")
>  c) numbers of examples suggest that outputs are separate from  
> sourcefile
> which is rarely true

I agree.

>
> Please take a look at attached picture to see how the new proposal  
> differs.
> The picture presents the idea - there is still room for visual  
> improvements
> via CSS etc.
>
> Upsides of proposed approach:
>  a) titles are meaningful, and you can choose them as you like
>  b) it is possible to create a useful list of examples (yes !)
>  c) sourcefile and output are grouped together which is more logical
>  d) the new code is backward-compatible - if you don't add a title,  
> you will
> get the filename (i.e. "build.gradle") as title.

Excellent.

>
> Downsides of proposed approach:
>  a) someone has to add titles for all examples (not necessarily -  
> keep on
> reading)
>
> I have written a patch that does all of it. The only change for  
> documentation
> creators, is that you will be kindly asked to add a new attribute to  
> sample
> tag - "title". But  as I said previously - you don't have to. For  
> example:
>        <sample id="upper" dir="userguide/tutorial/upper"  
> title="Simple Gradle
> tasks">
>            <sourcefile file="build.gradle"/>
>            <output args="-q upper"/>
>        </sample>
>
> I wanted to ask you if you like this idea. Any suggestions on how to  
> make it
> better ?

I like this idea very much. This is excellent stuff. I would wait  
until Adam is back (next week). He has done all the LaTeX2Docbook  
transformation. I would like him to have a look at it before applying  
the patch. And it would be really cool to have an additional appendix  
with the new expressive example names.

Thanks

- Hans

--
Hans Dockter
Gradle Project Manager
http://www.gradle.org



---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email

[Adam Murdoch-2]

tkaczano@... wrote:

Hi,

I've a suggestion regarding examples included in documentation.

Downsides of current approach:
  a) uninformative titles of examples ("build.gradle", "Output of gradle -q 
hello")
  b) because of this there is no way to create "list of examples" (because we 
have ~50 examples with the same title - "build.gradle")
  c) numbers of examples suggest that outputs are separate from sourcefile 
which is rarely true

Please take a look at attached picture to see how the new proposal differs.
The picture presents the idea - there is still room for visual improvements 
via CSS etc.

Upsides of proposed approach:
  a) titles are meaningful, and you can choose them as you like
  b) it is possible to create a useful list of examples (yes !)
  c) sourcefile and output are grouped together which is more logical
  d) the new code is backward-compatible - if you don't add a title, you will 
get the filename (i.e. "build.gradle") as title.

Downsides of proposed approach:
  a) someone has to add titles for all examples (not necessarily - keep on 
reading)

I have written a patch that does all of it. The only change for documentation 
creators, is that you will be kindly asked to add a new attribute to sample 
tag - "title". But  as I said previously - you don't have to. For example:
        <sample id="upper" dir="userguide/tutorial/upper" title="Simple Gradle 
tasks">
            <sourcefile file="build.gradle"/>
            <output args="-q upper"/>
        </sample>

I wanted to ask you if you like this idea.

I like this idea a lot.

 Any suggestions on how to make it 
better ?

  

Send us a patch :)

--
best regards
Tomek Kaczanowski
http://kaczanowscy.pl/tomek

  

---

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email