You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@jena.apache.org by Claude Warren <cl...@xenei.com> on 2013/07/24 09:51:41 UTC
Jena usage pattern documentation ?
I was just responding to a question on the users list concerning federated
queries and thought that it might be handy to have a set of documents that
describe how people are using Jena and how they overcome specific issues.
Not sure if there would be much in the way of contribution but I would
post overviews of how we solved various problems in the projects I have
been involved in. Is there any interest from other developers?
If so, I was thinking perhaps a wiki would be in order, if we can lock down
the authorship to keep spam out.
Thoughts?
Claude
--
I like: Like Like - The likeliest place on the web<http://like-like.xenei.com>
Identity: https://www.identify.nu/user.php?claude@xenei.com
LinkedIn: http://www.linkedin.com/in/claudewarren
Re: Jena usage pattern documentation ?
Posted by Claude Warren <cl...@xenei.com>.
yes
On Sat, Aug 10, 2013 at 10:17 AM, Andy Seaborne <an...@apache.org> wrote:
> Is this the sort of thing we're talking about?
>
> http://markmail.org/message/**jrxlnelijfzzqmxj<http://markmail.org/message/jrxlnelijfzzqmxj>
>
> Andy
>
>
> On 07/08/13 19:49, Andy Seaborne wrote:
>
>> On 07/08/13 13:14, Claude Warren wrote:
>>
>>> I was thinking PDF for longer pieces, something more like a paper. A
>>> document that says: this was our project, how we approached it, issues we
>>> encountered. More of a project look back or lessons learned document.
>>> Otherwise mdtext for everything else.
>>>
>>>
>>> On Wed, Aug 7, 2013 at 12:56 PM, Ian Dickinson <ia...@epimorphics.com>
>>> wrote:
>>>
>>> On 07/08/13 11:22, Claude Warren wrote:
>>>>
>>>> I have been thinking about this a bit more and am of the opinion
>>>>> that any
>>>>> new documentation should be "within" the current website and
>>>>> therefore the
>>>>> WIKI may not be the best solution.
>>>>>
>>>>
>> Claude - could you explain how you came to that opinion?
>>
>> There seems to be a difference between core documentation (factual,
>> about Jena itself) and usage (application architecture, experience and
>> opinion).
>>
>> There seem to me to be some disadvantages of hosting the content:
>>
>> 1/ Bottleneck.
>>
>> Committers has to update the website, and continue updating as the
>> material evolves; that seems a burden on the content writer as well. I'm
>> looking to see an advantage to compensate - what are your thoughts?
>>
>> Wouldn't a link to their content be more appropriate? They remain in
>> control and it can evolve as the author sees fit.
>>
>> I'm imaging that a common case is a useful blog item - why not leave on
>> the remote blog and link to it? Or an article on another site (e.g.
>> developerWorks).
>>
>> 2/ Experience is opinion: is this community in some way endorsing a
>> particular pattern or approach?
>>
>> 3/ What about questions about it? Bug reports?
>>
>> Discussion on users@ would be great but I wouldn't want to in any way
>> indirectly impose any obligation/expectation of that on a content
>> contributor.
>>
>> In summary: I think we should do anything we can to encourage material
>> being written. I am not making the connection that being on the current
>> website helps that - what am I missing?
>>
>> Andy
>>
>> Perhaps the easiest start would be to create a section titled "Usage
>>>>> and
>>>>> Design Patterns" in the site under the documentation section. I would
>>>>> propose that we place in this section items that are either longer than
>>>>> the
>>>>> "howto" currently found in the "notes" section or that span multiple
>>>>> components.
>>>>>
>>>>> Some thought needs to be given to navigation, especially as Samuel
>>>> Croset
>>>> is suggesting a change to the site IA as well as the look and feel
>>>> (as far
>>>> as I know, comments about the navigation structure below the
>>>> top-level are
>>>> as-yet unresolved in Samuel's redesign).
>>>>
>>>>
>>>> Documents in this section would be accepted in two basic formats:
>>>>
>>>>> 1) web (mdtext/html), may be multiple pages.
>>>>> 2) downloadable (pdf?), must include a single web page describing the
>>>>> document and providing the link to the download which would be in
>>>>> the jena
>>>>> documentation directory.
>>>>>
>>>>
>> Are there any examples of either of these already or is this a future
>> desire?
>>
>> Either would be great but teher is also the single page item whick (my
>> opinion) will be more common that a multipage one. YMMV
>>
>> Andy
>>
>>
>>>>> What's the use case for having downloadable pdf documents? Apart from
>>>> being less accessible to users and to search engines, they're also
>>>> hard for
>>>> anyone other than the original author to maintain. So for me: +1 to
>>>> contributions in mdtext or html (and I suggest that raw html should be
>>>> converted to mdtext using one of the many tools), -1 to pdf.
>>>>
>>>> Ian
>>>>
>>>>
>>>>
>>>
>>>
>>
>
--
I like: Like Like - The likeliest place on the web<http://like-like.xenei.com>
Identity: https://www.identify.nu/user.php?claude@xenei.com
LinkedIn: http://www.linkedin.com/in/claudewarren
Re: Jena usage pattern documentation ?
Posted by Andy Seaborne <an...@apache.org>.
Is this the sort of thing we're talking about?
http://markmail.org/message/jrxlnelijfzzqmxj
Andy
On 07/08/13 19:49, Andy Seaborne wrote:
> On 07/08/13 13:14, Claude Warren wrote:
>> I was thinking PDF for longer pieces, something more like a paper. A
>> document that says: this was our project, how we approached it, issues we
>> encountered. More of a project look back or lessons learned document.
>> Otherwise mdtext for everything else.
>>
>>
>> On Wed, Aug 7, 2013 at 12:56 PM, Ian Dickinson <ia...@epimorphics.com>
>> wrote:
>>
>>> On 07/08/13 11:22, Claude Warren wrote:
>>>
>>>> I have been thinking about this a bit more and am of the opinion
>>>> that any
>>>> new documentation should be "within" the current website and
>>>> therefore the
>>>> WIKI may not be the best solution.
>
> Claude - could you explain how you came to that opinion?
>
> There seems to be a difference between core documentation (factual,
> about Jena itself) and usage (application architecture, experience and
> opinion).
>
> There seem to me to be some disadvantages of hosting the content:
>
> 1/ Bottleneck.
>
> Committers has to update the website, and continue updating as the
> material evolves; that seems a burden on the content writer as well. I'm
> looking to see an advantage to compensate - what are your thoughts?
>
> Wouldn't a link to their content be more appropriate? They remain in
> control and it can evolve as the author sees fit.
>
> I'm imaging that a common case is a useful blog item - why not leave on
> the remote blog and link to it? Or an article on another site (e.g.
> developerWorks).
>
> 2/ Experience is opinion: is this community in some way endorsing a
> particular pattern or approach?
>
> 3/ What about questions about it? Bug reports?
>
> Discussion on users@ would be great but I wouldn't want to in any way
> indirectly impose any obligation/expectation of that on a content
> contributor.
>
> In summary: I think we should do anything we can to encourage material
> being written. I am not making the connection that being on the current
> website helps that - what am I missing?
>
> Andy
>
>>>> Perhaps the easiest start would be to create a section titled "Usage
>>>> and
>>>> Design Patterns" in the site under the documentation section. I would
>>>> propose that we place in this section items that are either longer than
>>>> the
>>>> "howto" currently found in the "notes" section or that span multiple
>>>> components.
>>>>
>>> Some thought needs to be given to navigation, especially as Samuel
>>> Croset
>>> is suggesting a change to the site IA as well as the look and feel
>>> (as far
>>> as I know, comments about the navigation structure below the
>>> top-level are
>>> as-yet unresolved in Samuel's redesign).
>>>
>>>
>>> Documents in this section would be accepted in two basic formats:
>>>> 1) web (mdtext/html), may be multiple pages.
>>>> 2) downloadable (pdf?), must include a single web page describing the
>>>> document and providing the link to the download which would be in
>>>> the jena
>>>> documentation directory.
>
> Are there any examples of either of these already or is this a future
> desire?
>
> Either would be great but teher is also the single page item whick (my
> opinion) will be more common that a multipage one. YMMV
>
> Andy
>
>>>>
>>> What's the use case for having downloadable pdf documents? Apart from
>>> being less accessible to users and to search engines, they're also
>>> hard for
>>> anyone other than the original author to maintain. So for me: +1 to
>>> contributions in mdtext or html (and I suggest that raw html should be
>>> converted to mdtext using one of the many tools), -1 to pdf.
>>>
>>> Ian
>>>
>>>
>>
>>
>
Re: Jena usage pattern documentation ?
Posted by Andy Seaborne <an...@apache.org>.
On 07/08/13 13:14, Claude Warren wrote:
> I was thinking PDF for longer pieces, something more like a paper. A
> document that says: this was our project, how we approached it, issues we
> encountered. More of a project look back or lessons learned document.
> Otherwise mdtext for everything else.
>
>
> On Wed, Aug 7, 2013 at 12:56 PM, Ian Dickinson <ia...@epimorphics.com> wrote:
>
>> On 07/08/13 11:22, Claude Warren wrote:
>>
>>> I have been thinking about this a bit more and am of the opinion that any
>>> new documentation should be "within" the current website and therefore the
>>> WIKI may not be the best solution.
Claude - could you explain how you came to that opinion?
There seems to be a difference between core documentation (factual,
about Jena itself) and usage (application architecture, experience and
opinion).
There seem to me to be some disadvantages of hosting the content:
1/ Bottleneck.
Committers has to update the website, and continue updating as the
material evolves; that seems a burden on the content writer as well.
I'm looking to see an advantage to compensate - what are your thoughts?
Wouldn't a link to their content be more appropriate? They remain in
control and it can evolve as the author sees fit.
I'm imaging that a common case is a useful blog item - why not leave on
the remote blog and link to it? Or an article on another site (e.g.
developerWorks).
2/ Experience is opinion: is this community in some way endorsing a
particular pattern or approach?
3/ What about questions about it? Bug reports?
Discussion on users@ would be great but I wouldn't want to in any way
indirectly impose any obligation/expectation of that on a content
contributor.
In summary: I think we should do anything we can to encourage material
being written. I am not making the connection that being on the current
website helps that - what am I missing?
Andy
>>> Perhaps the easiest start would be to create a section titled "Usage and
>>> Design Patterns" in the site under the documentation section. I would
>>> propose that we place in this section items that are either longer than
>>> the
>>> "howto" currently found in the "notes" section or that span multiple
>>> components.
>>>
>> Some thought needs to be given to navigation, especially as Samuel Croset
>> is suggesting a change to the site IA as well as the look and feel (as far
>> as I know, comments about the navigation structure below the top-level are
>> as-yet unresolved in Samuel's redesign).
>>
>>
>> Documents in this section would be accepted in two basic formats:
>>> 1) web (mdtext/html), may be multiple pages.
>>> 2) downloadable (pdf?), must include a single web page describing the
>>> document and providing the link to the download which would be in the jena
>>> documentation directory.
Are there any examples of either of these already or is this a future
desire?
Either would be great but teher is also the single page item whick (my
opinion) will be more common that a multipage one. YMMV
Andy
>>>
>> What's the use case for having downloadable pdf documents? Apart from
>> being less accessible to users and to search engines, they're also hard for
>> anyone other than the original author to maintain. So for me: +1 to
>> contributions in mdtext or html (and I suggest that raw html should be
>> converted to mdtext using one of the many tools), -1 to pdf.
>>
>> Ian
>>
>>
>
>
Re: Jena usage pattern documentation ?
Posted by Claude Warren <cl...@xenei.com>.
I was thinking PDF for longer pieces, something more like a paper. A
document that says: this was our project, how we approached it, issues we
encountered. More of a project look back or lessons learned document.
Otherwise mdtext for everything else.
On Wed, Aug 7, 2013 at 12:56 PM, Ian Dickinson <ia...@epimorphics.com> wrote:
> On 07/08/13 11:22, Claude Warren wrote:
>
>> I have been thinking about this a bit more and am of the opinion that any
>> new documentation should be "within" the current website and therefore the
>> WIKI may not be the best solution.
>>
>> Perhaps the easiest start would be to create a section titled "Usage and
>> Design Patterns" in the site under the documentation section. I would
>> propose that we place in this section items that are either longer than
>> the
>> "howto" currently found in the "notes" section or that span multiple
>> components.
>>
> Some thought needs to be given to navigation, especially as Samuel Croset
> is suggesting a change to the site IA as well as the look and feel (as far
> as I know, comments about the navigation structure below the top-level are
> as-yet unresolved in Samuel's redesign).
>
>
> Documents in this section would be accepted in two basic formats:
>> 1) web (mdtext/html), may be multiple pages.
>> 2) downloadable (pdf?), must include a single web page describing the
>> document and providing the link to the download which would be in the jena
>> documentation directory.
>>
> What's the use case for having downloadable pdf documents? Apart from
> being less accessible to users and to search engines, they're also hard for
> anyone other than the original author to maintain. So for me: +1 to
> contributions in mdtext or html (and I suggest that raw html should be
> converted to mdtext using one of the many tools), -1 to pdf.
>
> Ian
>
>
--
I like: Like Like - The likeliest place on the web<http://like-like.xenei.com>
Identity: https://www.identify.nu/user.php?claude@xenei.com
LinkedIn: http://www.linkedin.com/in/claudewarren
Re: Jena usage pattern documentation ?
Posted by Ian Dickinson <ia...@epimorphics.com>.
On 07/08/13 19:34, Andy Seaborne wrote:
> On 07/08/13 12:56, Ian Dickinson wrote:
>> Some thought needs to be given to navigation, especially as Samuel
>> Croset is suggesting a change to the site IA as well as the look and
>> feel (as far as I know, comments about the navigation structure below
>> the top-level are as-yet unresolved in Samuel's redesign).
>
> JENA-482
>
> My understanding is that the website IA remains the same - it's the
> look&feel that the contribution is about.
The problem is, as has been mentioned in the JENA-482 comments, that the
current site has a multi-level navigation hierarchy: once you get into a
topic - say, documentation, the LH menu expands to show more options.
This serves both to orient the user and to progressively offer more
options than can fit in a single menu level. Samuel's initial redesign
doesn't have navigation affordances below the top-level menu, something
he said he was going to look at. Whether that's IA or just site L&F is
somewhat a grey area: the current directory structure isn't changing but
the overall site structure as experienced by the user is.
Ian
Re: Jena usage pattern documentation ?
Posted by Andy Seaborne <an...@apache.org>.
On 07/08/13 12:56, Ian Dickinson wrote:
> Some thought needs to be given to navigation, especially as Samuel
> Croset is suggesting a change to the site IA as well as the look and
> feel (as far as I know, comments about the navigation structure below
> the top-level are as-yet unresolved in Samuel's redesign).
JENA-482
My understanding is that the website IA remains the same - it's the
look&feel that the contribution is about.
Andy
Re: Jena usage pattern documentation ?
Posted by Ian Dickinson <ia...@epimorphics.com>.
On 07/08/13 11:22, Claude Warren wrote:
> I have been thinking about this a bit more and am of the opinion that any
> new documentation should be "within" the current website and therefore the
> WIKI may not be the best solution.
>
> Perhaps the easiest start would be to create a section titled "Usage and
> Design Patterns" in the site under the documentation section. I would
> propose that we place in this section items that are either longer than the
> "howto" currently found in the "notes" section or that span multiple
> components.
Some thought needs to be given to navigation, especially as Samuel
Croset is suggesting a change to the site IA as well as the look and
feel (as far as I know, comments about the navigation structure below
the top-level are as-yet unresolved in Samuel's redesign).
> Documents in this section would be accepted in two basic formats:
> 1) web (mdtext/html), may be multiple pages.
> 2) downloadable (pdf?), must include a single web page describing the
> document and providing the link to the download which would be in the jena
> documentation directory.
What's the use case for having downloadable pdf documents? Apart from
being less accessible to users and to search engines, they're also hard
for anyone other than the original author to maintain. So for me: +1 to
contributions in mdtext or html (and I suggest that raw html should be
converted to mdtext using one of the many tools), -1 to pdf.
Ian
Re: Jena usage pattern documentation ?
Posted by Claude Warren <cl...@xenei.com>.
I have been thinking about this a bit more and am of the opinion that any
new documentation should be "within" the current website and therefore the
WIKI may not be the best solution.
Perhaps the easiest start would be to create a section titled "Usage and
Design Patterns" in the site under the documentation section. I would
propose that we place in this section items that are either longer than the
"howto" currently found in the "notes" section or that span multiple
components.
Documents in this section would be accepted in two basic formats:
1) web (mdtext/html), may be multiple pages.
2) downloadable (pdf?), must include a single web page describing the
document and providing the link to the download which would be in the jena
documentation directory.
Information required within the document should be: author, original date,
version of Jena and associated libraries, date of last update.
Is there any objection or additions to the above?
Claude
On Tue, Jul 30, 2013 at 1:44 PM, Andy Seaborne <an...@apache.org> wrote:
> On 24/07/13 09:06, Sarven Capadisli wrote:
>
>> On 07/24/2013 09:51 AM, Claude Warren wrote:
>>
>>> I was just responding to a question on the users list concerning
>>> federated
>>> queries and thought that it might be handy to have a set of documents
>>> that
>>> describe how people are using Jena and how they overcome specific issues.
>>> Not sure if there would be much in the way of contribution but I would
>>> post overviews of how we solved various problems in the projects I have
>>> been involved in. Is there any interest from other developers?
>>>
>>
> Yes.
>
>
>
>>> If so, I was thinking perhaps a wiki would be in order, if we can lock
>>> down the authorship to keep spam out.
>>>
>>
> The project has
>
> https://cwiki.apache.org/**confluence/display/JENA/<https://cwiki.apache.org/confluence/display/JENA/>
>
> and there is also
>
> http://wiki.apache.org/**general/ <http://wiki.apache.org/general/>
>
> Andy
>
>
>
>>> Thoughts?
>>>
>>> Claude
>>>
>>>
>> I think this would be useful for the community, even a FAQ type of stuff
>> would be handy. Or open problems that we don't yet know how to deal with.
>>
>> Keep in mind that http://answers.semanticweb.**com/<http://answers.semanticweb.com/>contains useful Q&As
>> which we could make it to the Jena wiki - a cleaned up, perhaps a step
>> by step on how-tos for some questions.
>>
>> Ditto the users mailing list.
>>
>
> Yes - the best first step is generate some content at minimal overhead.
> If it proves successful, it can be organised.
>
> Claude - thoughts?
>
>
>> -Sarven
>>
>>
>
--
I like: Like Like - The likeliest place on the web<http://like-like.xenei.com>
Identity: https://www.identify.nu/user.php?claude@xenei.com
LinkedIn: http://www.linkedin.com/in/claudewarren
Re: Jena usage pattern documentation ?
Posted by Andy Seaborne <an...@apache.org>.
On 24/07/13 09:06, Sarven Capadisli wrote:
> On 07/24/2013 09:51 AM, Claude Warren wrote:
>> I was just responding to a question on the users list concerning
>> federated
>> queries and thought that it might be handy to have a set of documents
>> that
>> describe how people are using Jena and how they overcome specific issues.
>> Not sure if there would be much in the way of contribution but I would
>> post overviews of how we solved various problems in the projects I have
>> been involved in. Is there any interest from other developers?
Yes.
>>
>> If so, I was thinking perhaps a wiki would be in order, if we can lock
>> down the authorship to keep spam out.
The project has
https://cwiki.apache.org/confluence/display/JENA/
and there is also
http://wiki.apache.org/general/
Andy
>>
>> Thoughts?
>>
>> Claude
>>
>
> I think this would be useful for the community, even a FAQ type of stuff
> would be handy. Or open problems that we don't yet know how to deal with.
>
> Keep in mind that http://answers.semanticweb.com/ contains useful Q&As
> which we could make it to the Jena wiki - a cleaned up, perhaps a step
> by step on how-tos for some questions.
>
> Ditto the users mailing list.
Yes - the best first step is generate some content at minimal overhead.
If it proves successful, it can be organised.
Claude - thoughts?
>
> -Sarven
>
Re: Jena usage pattern documentation ?
Posted by Sarven Capadisli <in...@csarven.ca>.
On 07/24/2013 09:51 AM, Claude Warren wrote:
> I was just responding to a question on the users list concerning federated
> queries and thought that it might be handy to have a set of documents that
> describe how people are using Jena and how they overcome specific issues.
> Not sure if there would be much in the way of contribution but I would
> post overviews of how we solved various problems in the projects I have
> been involved in. Is there any interest from other developers?
>
> If so, I was thinking perhaps a wiki would be in order, if we can lock down
> the authorship to keep spam out.
>
> Thoughts?
>
> Claude
>
I think this would be useful for the community, even a FAQ type of stuff
would be handy. Or open problems that we don't yet know how to deal with.
Keep in mind that http://answers.semanticweb.com/ contains useful Q&As
which we could make it to the Jena wiki - a cleaned up, perhaps a step
by step on how-tos for some questions.
Ditto the users mailing list.
-Sarven