Re: Documentation effort

Dear all,

I just created a new repo that contains a README template for RDFJS libraries [1].
If you have any feedback on this template, feel free to open PRs/issues on the repo.

I also opened a pull request to add a pull request template [2]
for the RDFJS website corresponding to these recommendations.
If you have any concerns, or if you agree with this, please leave a review on the PR.

Unless any major concerns arise, I will merge this PR over two weeks (December 2nd).

[1] https://github.com/rdfjs/lib-template/
[2] https://github.com/rdfjs/rdfjs.github.io/pull/8

Kind regards,
Ruben Taelman

On 14 October 2019 at 10:25:17, Jacopo Scazzosi (jacopo@scazzosi.com) wrote:

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