Documentation enhancement - index

> Hi,
>
> sometimes when I am getting into planning a new feature to add to our
> application, and I try one of the examples, and I look at the source,
> I'll see something, and I'll think, "that looks useful, I wonder what
> it's supposed to do, or what the full syntax is", or something like
> that. And then you have to go hunting. Sometimes the contents down the
> left of the docs web page will get you there, but there are many times
> when the association is not intuitive (or I'm just having a cross-eyed
> day!) and then I have to go grep the doc directory.
>
> It would seem it could be very useful to have an (or many) index into
> the doc.
> The thing I am most thinking of would be a list of processors.
> Thanks to grep and bbedit I produced a list of processors used in the
> examples, and there are over 90.
> Some I'd never heard of.
> Some of them will be very useful in the future.
> Seeing the list took me straight to something I needed (straight in as
> I knew it existed, I still had to grep the docs to find which page it
> was in and then use the contents to go to that page - you see how I
> think there is room for improvement ;-).
>
> Some of those new-to-me processors were also undocumented, but that's
> another story.
>
> Hope this makes sense
> thanks & regards
> Colin
>
>
>
>
>
> --
> You receive this message as a subscriber of the [hidden email] mailing list.
> To unsubscribe: mailto:[hidden email]
> For general help: mailto:[hidden email]?subject=help
> ObjectWeb mailing lists service home page: http://www.objectweb.org/wws
>
>
>

> Hi Colin,
>
> 1) If you know what you are looking for, Google provides a pretty good
> index. If you are looking for the SQL processor documentation, then
> search on Google for: site:www.orbeon.com sql processor. Sometimes it
> is faster to just type what you are looking for then looking it up in
> the documentation table of contents.
>
> 2) But I agree: we don't have a place where we just list all the
> available processors. In the documentation, they are grouped by
> categories under "Processors Reference". If you want to create a page
> with the alphabetical list of processors, a one line description for
> each one, and a link to the appropriate section of the documentation,
> we would be happy to include this list in the documentation. For the
> format to use, look at the XML files under doc/pages in the examples
> resources.
>
> Alex
>
> On 1/6/06, Colin O'Brien <[hidden email]> wrote:
>> Hi,
>>
>> sometimes when I am getting into planning a new feature to add to our
>> application, and I try one of the examples, and I look at the source,
>> I'll see something, and I'll think, "that looks useful, I wonder what
>> it's supposed to do, or what the full syntax is", or something like
>> that. And then you have to go hunting. Sometimes the contents down the
>> left of the docs web page will get you there, but there are many times
>> when the association is not intuitive (or I'm just having a cross-eyed
>> day!) and then I have to go grep the doc directory.
>>
>> It would seem it could be very useful to have an (or many) index into
>> the doc.
>> The thing I am most thinking of would be a list of processors.
>> Thanks to grep and bbedit I produced a list of processors used in the
>> examples, and there are over 90.
>> Some I'd never heard of.
>> Some of them will be very useful in the future.
>> Seeing the list took me straight to something I needed (straight in as
>> I knew it existed, I still had to grep the docs to find which page it
>> was in and then use the contents to go to that page - you see how I
>> think there is room for improvement ;-).
>>
>> Some of those new-to-me processors were also undocumented, but that's
>> another story.
>>
>> Hope this makes sense
>> thanks & regards
>> Colin
>>
>>
>>
>>
>>
>> --
>> You receive this message as a subscriber of the
>> [hidden email] mailing list.
>> To unsubscribe: mailto:[hidden email]
>> For general help: mailto:[hidden email]?subject=help
>> ObjectWeb mailing lists service home page:
>> http://www.objectweb.org/wws
>>
>>
>>
>
>
> --
> Blog (XML, Web apps, Open Source): http://www.orbeon.com/blog/
>
>
> --
> You receive this message as a subscriber of the
> [hidden email] mailing list.
> To unsubscribe: mailto:[hidden email]
> For general help: mailto:[hidden email]?subject=help
> ObjectWeb mailing lists service home page: http://www.objectweb.org/wws

> Hi Alex
>
> yes, Google can be useful once you know what you are using, but an
> index can be useful when you just have a vague idea of what you want to
> accomplish but not the OPS term for it.
>
> And yes, since I've already started ;-) I can make a first pass at
> producing the index of processors. I will have to leave it to you to
> finish it though, as I'm not sure what they all do!
>
> Thanks & regards
> Colin
>
> On Jan 6, 2006, at 5:15 PM, Alessandro Vernet wrote:
>
> > Hi Colin,
> >
> > 1) If you know what you are looking for, Google provides a pretty good
> > index. If you are looking for the SQL processor documentation, then
> > search on Google for: site:www.orbeon.com sql processor. Sometimes it
> > is faster to just type what you are looking for then looking it up in
> > the documentation table of contents.
> >
> > 2) But I agree: we don't have a place where we just list all the
> > available processors. In the documentation, they are grouped by
> > categories under "Processors Reference". If you want to create a page
> > with the alphabetical list of processors, a one line description for
> > each one, and a link to the appropriate section of the documentation,
> > we would be happy to include this list in the documentation. For the
> > format to use, look at the XML files under doc/pages in the examples
> > resources.
> >
> > Alex
> >
> > On 1/6/06, Colin O'Brien <[hidden email]> wrote:
> >> Hi,
> >>
> >> sometimes when I am getting into planning a new feature to add to our
> >> application, and I try one of the examples, and I look at the source,
> >> I'll see something, and I'll think, "that looks useful, I wonder what
> >> it's supposed to do, or what the full syntax is", or something like
> >> that. And then you have to go hunting. Sometimes the contents down the
> >> left of the docs web page will get you there, but there are many times
> >> when the association is not intuitive (or I'm just having a cross-eyed
> >> day!) and then I have to go grep the doc directory.
> >>
> >> It would seem it could be very useful to have an (or many) index into
> >> the doc.
> >> The thing I am most thinking of would be a list of processors.
> >> Thanks to grep and bbedit I produced a list of processors used in the
> >> examples, and there are over 90.
> >> Some I'd never heard of.
> >> Some of them will be very useful in the future.
> >> Seeing the list took me straight to something I needed (straight in as
> >> I knew it existed, I still had to grep the docs to find which page it
> >> was in and then use the contents to go to that page - you see how I
> >> think there is room for improvement ;-).
> >>
> >> Some of those new-to-me processors were also undocumented, but that's
> >> another story.
> >>
> >> Hope this makes sense
> >> thanks & regards
> >> Colin
> >>
> >>
> >>
> >>
> >>
> >> --
> >> You receive this message as a subscriber of the
> >> [hidden email] mailing list.
> >> To unsubscribe: mailto:[hidden email]
> >> For general help: mailto:[hidden email]?subject=help
> >> ObjectWeb mailing lists service home page:
> >> http://www.objectweb.org/wws
> >>
> >>
> >>
> >
> >
> > --
> > Blog (XML, Web apps, Open Source): http://www.orbeon.com/blog/
> >
> >
> > --
> > You receive this message as a subscriber of the
> > [hidden email] mailing list.
> > To unsubscribe: mailto:[hidden email]
> > For general help: mailto:[hidden email]?subject=help
> > ObjectWeb mailing lists service home page: http://www.objectweb.org/wws
>
>
>
>
>
> --
> You receive this message as a subscriber of the [hidden email] mailing list.
> To unsubscribe: mailto:[hidden email]
> For general help: mailto:[hidden email]?subject=help
> ObjectWeb mailing lists service home page: http://www.objectweb.org/wws
>
>
>