An idea to improve the documentation

classic Classic list List threaded Threaded
9 messages Options
Reply | Threaded
Open this post in threaded view
|

An idea to improve the documentation

Muhammad Gelbana
How about including references (links or embedded) to relative tapestry
source code within a documentation page ?

This could be even more informative than the documentation itself since it
has every detail, while the documentation only explains

*---------------------*
*Muhammad Gelbana*
http://www.linkedin.com/in/mgelbana
Reply | Threaded
Open this post in threaded view
|

Re: An idea to improve the documentation

Muhammad Gelbana
Opps ! Just hist a mysterious keyboard shortcut to send emails from GMail !!

Anyway, so the documentation page will discuss the subject thoroughly while
advanced users and source code explorers will have a better experience and
less time finding the relevant source code for the subject being discussed
in the documentation.

What do you think ?

*---------------------*
*Muhammad Gelbana*
http://www.linkedin.com/in/mgelbana


On Mon, Oct 14, 2013 at 1:07 PM, Muhammad Gelbana <[hidden email]>wrote:

> How about including references (links or embedded) to relative tapestry
> source code within a documentation page ?
>
> This could be even more informative than the documentation itself since it
> has every detail, while the documentation only explains
>
> *---------------------*
> *Muhammad Gelbana*
> http://www.linkedin.com/in/mgelbana
>
Reply | Threaded
Open this post in threaded view
|

Re: An idea to improve the documentation

bobharner
A good idea, although there is some added risk of broken links as source
code gets moved around with new releases. Do you have any specific places
in the documentation where you think a link to Tapestry's source code would
be helpful?


On Mon, Oct 14, 2013 at 7:09 AM, Muhammad Gelbana <[hidden email]>wrote:

> Opps ! Just hist a mysterious keyboard shortcut to send emails from GMail
> !!
>
> Anyway, so the documentation page will discuss the subject thoroughly while
> advanced users and source code explorers will have a better experience and
> less time finding the relevant source code for the subject being discussed
> in the documentation.
>
> What do you think ?
>
> *---------------------*
> *Muhammad Gelbana*
> http://www.linkedin.com/in/mgelbana
>
>
> On Mon, Oct 14, 2013 at 1:07 PM, Muhammad Gelbana <[hidden email]
> >wrote:
>
> > How about including references (links or embedded) to relative tapestry
> > source code within a documentation page ?
> >
> > This could be even more informative than the documentation itself since
> it
> > has every detail, while the documentation only explains
> >
> > *---------------------*
> > *Muhammad Gelbana*
> > http://www.linkedin.com/in/mgelbana
> >
>
Reply | Threaded
Open this post in threaded view
|

Re: An idea to improve the documentation

Muhammad Gelbana
May be within topics discussing internal Tapestry logic that is usually a
mystique for new users and for me included like injection, request
handling, how mixins work.

Anywhere possible should be helpful though.

And about the documentation in general. Is it possible to have separate
documentation for each Tapestry version ? I think this would make it easier
to implement new documentation ideas such as this idea.

*---------------------*
*Muhammad Gelbana*
http://www.linkedin.com/in/mgelbana


On Mon, Oct 14, 2013 at 1:17 PM, Bob Harner <[hidden email]> wrote:

> A good idea, although there is some added risk of broken links as source
> code gets moved around with new releases. Do you have any specific places
> in the documentation where you think a link to Tapestry's source code would
> be helpful?
>
>
> On Mon, Oct 14, 2013 at 7:09 AM, Muhammad Gelbana <[hidden email]
> >wrote:
>
> > Opps ! Just hist a mysterious keyboard shortcut to send emails from GMail
> > !!
> >
> > Anyway, so the documentation page will discuss the subject thoroughly
> while
> > advanced users and source code explorers will have a better experience
> and
> > less time finding the relevant source code for the subject being
> discussed
> > in the documentation.
> >
> > What do you think ?
> >
> > *---------------------*
> > *Muhammad Gelbana*
> > http://www.linkedin.com/in/mgelbana
> >
> >
> > On Mon, Oct 14, 2013 at 1:07 PM, Muhammad Gelbana <[hidden email]
> > >wrote:
> >
> > > How about including references (links or embedded) to relative tapestry
> > > source code within a documentation page ?
> > >
> > > This could be even more informative than the documentation itself since
> > it
> > > has every detail, while the documentation only explains
> > >
> > > *---------------------*
> > > *Muhammad Gelbana*
> > > http://www.linkedin.com/in/mgelbana
> > >
> >
>
Reply | Threaded
Open this post in threaded view
|

Re: An idea to improve the documentation

abangkis
In reply to this post by bobharner
I think the Android documentation is a great example for this

http://developer.android.com/reference/android/app/Activity.html

As you see in the link, you can click the (view source) link beside each
class name to view the related source code.


On Mon, Oct 14, 2013 at 6:17 PM, Bob Harner <[hidden email]> wrote:

> A good idea, although there is some added risk of broken links as source
> code gets moved around with new releases. Do you have any specific places
> in the documentation where you think a link to Tapestry's source code would
> be helpful?
>
>
> On Mon, Oct 14, 2013 at 7:09 AM, Muhammad Gelbana <[hidden email]
> >wrote:
>
> > Opps ! Just hist a mysterious keyboard shortcut to send emails from GMail
> > !!
> >
> > Anyway, so the documentation page will discuss the subject thoroughly
> while
> > advanced users and source code explorers will have a better experience
> and
> > less time finding the relevant source code for the subject being
> discussed
> > in the documentation.
> >
> > What do you think ?
> >
> > *---------------------*
> > *Muhammad Gelbana*
> > http://www.linkedin.com/in/mgelbana
> >
> >
> > On Mon, Oct 14, 2013 at 1:07 PM, Muhammad Gelbana <[hidden email]
> > >wrote:
> >
> > > How about including references (links or embedded) to relative tapestry
> > > source code within a documentation page ?
> > >
> > > This could be even more informative than the documentation itself since
> > it
> > > has every detail, while the documentation only explains
> > >
> > > *---------------------*
> > > *Muhammad Gelbana*
> > > http://www.linkedin.com/in/mgelbana
> > >
> >
>



--
http://www.mreunionlabs.net/ <http://www.mreunion-labs.net/>
twitter : @mreunionlabs
page : https://plus.google.com/104168782385184990771
Reply | Threaded
Open this post in threaded view
|

Re: An idea to improve the documentation

bobharner
Muhammad: I'd much rather have one good version of the documentation, with
notes about the differences, than dozens of mostly redundant versions.

Also, I don't see how having separate documentation for each version makes
it easier to implement new documentation ideas. Quite the opposite, since
you'd be multiplying the amount of content to manage and update. Redundancy
in documentation is just as bad as redundancy in code, and for mostly the
same reasons.


On Mon, Oct 14, 2013 at 1:04 PM, abangkis <[hidden email]> wrote:

> I think the Android documentation is a great example for this
>
> http://developer.android.com/reference/android/app/Activity.html
>
> As you see in the link, you can click the (view source) link beside each
> class name to view the related source code.
>
>
> On Mon, Oct 14, 2013 at 6:17 PM, Bob Harner <[hidden email]> wrote:
>
> > A good idea, although there is some added risk of broken links as source
> > code gets moved around with new releases. Do you have any specific places
> > in the documentation where you think a link to Tapestry's source code
> would
> > be helpful?
> >
> >
> > On Mon, Oct 14, 2013 at 7:09 AM, Muhammad Gelbana <[hidden email]
> > >wrote:
> >
> > > Opps ! Just hist a mysterious keyboard shortcut to send emails from
> GMail
> > > !!
> > >
> > > Anyway, so the documentation page will discuss the subject thoroughly
> > while
> > > advanced users and source code explorers will have a better experience
> > and
> > > less time finding the relevant source code for the subject being
> > discussed
> > > in the documentation.
> > >
> > > What do you think ?
> > >
> > > *---------------------*
> > > *Muhammad Gelbana*
> > > http://www.linkedin.com/in/mgelbana
> > >
> > >
> > > On Mon, Oct 14, 2013 at 1:07 PM, Muhammad Gelbana <[hidden email]
> > > >wrote:
> > >
> > > > How about including references (links or embedded) to relative
> tapestry
> > > > source code within a documentation page ?
> > > >
> > > > This could be even more informative than the documentation itself
> since
> > > it
> > > > has every detail, while the documentation only explains
> > > >
> > > > *---------------------*
> > > > *Muhammad Gelbana*
> > > > http://www.linkedin.com/in/mgelbana
> > > >
> > >
> >
>
>
>
> --
> http://www.mreunionlabs.net/ <http://www.mreunion-labs.net/>
> twitter : @mreunionlabs
> page : https://plus.google.com/104168782385184990771
>
Reply | Threaded
Open this post in threaded view
|

Re: An idea to improve the documentation

Muhammad Gelbana
I see your point Bob, It could be better the way it is.

My point is if we different version of documentations for different
versions of tapestry. Then we won't bother with broken source code links
since each documentation version will statically refer to it's relevant
source code.

Anyway, if the "Links to source code" initiative got carried out, I'd be
glad to help if I can. I'm still lost in the source code my self :D

*---------------------*
*Muhammad Gelbana*
http://www.linkedin.com/in/mgelbana


On Mon, Oct 14, 2013 at 10:15 PM, Bob Harner <[hidden email]> wrote:

> Muhammad: I'd much rather have one good version of the documentation, with
> notes about the differences, than dozens of mostly redundant versions.
>
> Also, I don't see how having separate documentation for each version makes
> it easier to implement new documentation ideas. Quite the opposite, since
> you'd be multiplying the amount of content to manage and update. Redundancy
> in documentation is just as bad as redundancy in code, and for mostly the
> same reasons.
>
>
> On Mon, Oct 14, 2013 at 1:04 PM, abangkis <[hidden email]> wrote:
>
> > I think the Android documentation is a great example for this
> >
> > http://developer.android.com/reference/android/app/Activity.html
> >
> > As you see in the link, you can click the (view source) link beside each
> > class name to view the related source code.
> >
> >
> > On Mon, Oct 14, 2013 at 6:17 PM, Bob Harner <[hidden email]> wrote:
> >
> > > A good idea, although there is some added risk of broken links as
> source
> > > code gets moved around with new releases. Do you have any specific
> places
> > > in the documentation where you think a link to Tapestry's source code
> > would
> > > be helpful?
> > >
> > >
> > > On Mon, Oct 14, 2013 at 7:09 AM, Muhammad Gelbana <[hidden email]
> > > >wrote:
> > >
> > > > Opps ! Just hist a mysterious keyboard shortcut to send emails from
> > GMail
> > > > !!
> > > >
> > > > Anyway, so the documentation page will discuss the subject thoroughly
> > > while
> > > > advanced users and source code explorers will have a better
> experience
> > > and
> > > > less time finding the relevant source code for the subject being
> > > discussed
> > > > in the documentation.
> > > >
> > > > What do you think ?
> > > >
> > > > *---------------------*
> > > > *Muhammad Gelbana*
> > > > http://www.linkedin.com/in/mgelbana
> > > >
> > > >
> > > > On Mon, Oct 14, 2013 at 1:07 PM, Muhammad Gelbana <
> [hidden email]
> > > > >wrote:
> > > >
> > > > > How about including references (links or embedded) to relative
> > tapestry
> > > > > source code within a documentation page ?
> > > > >
> > > > > This could be even more informative than the documentation itself
> > since
> > > > it
> > > > > has every detail, while the documentation only explains
> > > > >
> > > > > *---------------------*
> > > > > *Muhammad Gelbana*
> > > > > http://www.linkedin.com/in/mgelbana
> > > > >
> > > >
> > >
> >
> >
> >
> > --
> > http://www.mreunionlabs.net/ <http://www.mreunion-labs.net/>
> > twitter : @mreunionlabs
> > page : https://plus.google.com/104168782385184990771
> >
>
Reply | Threaded
Open this post in threaded view
|

Re: An idea to improve the documentation

Thiago H de Paula Figueiredo
On Mon, 14 Oct 2013 17:43:02 -0300, Muhammad Gelbana <[hidden email]>  
wrote:

> I see your point Bob, It could be better the way it is.
>
> My point is if we different version of documentations for different
> versions of tapestry. Then we won't bother with broken source code links
> since each documentation version will statically refer to it's relevant
> source code.

I'm sorry, Muhammad, but that would be hell to maintain. Imagine you wrote  
a better description for something. Now you'd had to update at least for  
documents for that. (5.1, 5.2, 5.3, 5.4). I'd give an automatic -1 vote on  
that. We need to simplify stuff, not complicate them. People would  
probably read documentation about the wrong version and not notice. In  
addition, in Tapestry 5, things change in non-backward ways in a  
veeeeeeery slow pace.

--
Thiago H. de Paula Figueiredo
Tapestry, Java and Hibernate consultant and developer
http://machina.com.br

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: An idea to improve the documentation

trsvax
I don't think you can solve this problem with static online documentation.
Something as simple as what are the type coercers is not something you can
document online since it's possible to add the dynamically. They only way
to solve this is generate the documentation for the running system. This
also has the benefit of documenting the version you are running. I think
it's possible to do this an additional burden on the developers since Java
already has standards (Javadoc) for this.


On Mon, Oct 14, 2013 at 3:48 PM, Thiago H de Paula Figueiredo <
[hidden email]> wrote:

> On Mon, 14 Oct 2013 17:43:02 -0300, Muhammad Gelbana <[hidden email]>
> wrote:
>
>  I see your point Bob, It could be better the way it is.
>>
>> My point is if we different version of documentations for different
>> versions of tapestry. Then we won't bother with broken source code links
>> since each documentation version will statically refer to it's relevant
>> source code.
>>
>
> I'm sorry, Muhammad, but that would be hell to maintain. Imagine you wrote
> a better description for something. Now you'd had to update at least for
> documents for that. (5.1, 5.2, 5.3, 5.4). I'd give an automatic -1 vote on
> that. We need to simplify stuff, not complicate them. People would probably
> read documentation about the wrong version and not notice. In addition, in
> Tapestry 5, things change in non-backward ways in a veeeeeeery slow pace.
>
> --
> Thiago H. de Paula Figueiredo
> Tapestry, Java and Hibernate consultant and developer
> http://machina.com.br
>
> ------------------------------**------------------------------**---------
> To unsubscribe, e-mail: users-unsubscribe@tapestry.**apache.org<[hidden email]>
> For additional commands, e-mail: [hidden email]
>
>