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 <[email protected]>
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
