Re: Documentation effort

Hello Ruben.

I think you’re absolutely right. There’s an issue on quadstore that laments the lack of examples which I’ve been meaning to address for a while but have yet to do so for a myriad of reasons, including my own personal bias towards the technical side of things.

> We could even go a step further, and enforce a minimum set of documentation requirements for all the tools that are listed on rdf.js.org

I like the sound of this.

Best regards,
Jacopo Scazzosi.


> On 14 Oct 2019, at 10:16, Ruben Taelman <ruben.taelman@ugent.be> wrote:
> 
> Dear all,
> 
> I've been hearing some concerns regarding the documentation of RDFJS tools,
> and that it is hindering the adoption of these tools.
> In my latest blog post [1], I've made an attempt to offer an overview of the existing tools,
> but I think we need to improve the documentation of each tool separately as well.
> 
> Some of the main issues seem to be:
> * not enough examples
> * missing overview of available features
> * missing links to compatible/related tools
> 
> I believe we can solve these issues by initiating a documentation effort,
> where we define some guidelines on what elements are essential for such documentation.
> For example, we could offer a README template with some
> essential sections that can be filled in by RDFJS tool developers.
> 
> We could even go a step further, and enforce a minimum set of documentation requirements
> for all the tools that are listed on rdf.js.org.
> 
> Any thoughts on this?
> If people agree, I'd be happy to create a first version of such a documentation template,
> for which we could create some kind of best practises repo.
> 
> [1] https://www.rubensworks.net/blog/2019/10/06/using-rdf-in-javascript/
> 
> Kind regards,
> Ruben Taelman

Received on Monday, 14 October 2019 12:09:13 UTC