creativecommons/legaldb

[Feature] Addition of a guides folder for beginner to this project

Closed this issue · 4 comments

egbadon-victor commented

Problem

Beginners to the creativecommons/legaldb project may find it difficult to understand the legaldb project structure, and even set it up. While the README file can be improved, I think beginners would benefit from more explicit instructions and explanations.

Description

Inspired by the guides folder in the creativecommons/search repository, implementing a guides/ folder would help new contributors get acquainted with the project, and provide valuable tutorials on the basic interactions on this project.

Alternatives

  • Make the README file more explicit as captured in #202 . This would make the README a bit too much for someone who is already familiar and just wants to get going.
  • Document all the guides in the SisiVero/CCGuides repo. The problem with this is that there is no link that point to the repo as a source of guides.

Implementation

  • I would be interested in implementing this feature.
TimidRobot commented

@egbadon-victor (and others) please provide more information on what specific guides you think would be helpful (that are not already covered by the guides on Creative Commons Open Source

egbadon-victor commented

Okay @TimidRobot

Things we could include in the guide would be very specific to legaldb. Going through the Creative Commons Open Source, the only reference to legaldb is a link to the repo here on github. Hence the aim of the guides would be a hands on, quick setup guide covered in detail, especially helpful for beginners or new contributors.

Here are examples of specific guides;

  • Simple git tutorial, highlighting exact commands for command scenarios encountered when working with legaldb
  • Simple explanation on the technologies used in the repo, how it is being used, and where contributors can get official help (more like our recommendation)
  • More explicit setup instructions, tailored to be beginner friendly

Most of these suggestions are tailored to beginners, and I think that is the basic essence. More advanced contributors are familiar with project structure in general, and often know where to search solutions if they have any problems.

TimidRobot commented

@egbadon-victor of the examples provided, I think Simple explanation on the technologies used in the repo, how it is being used, and where contributors can get official help (more like our recommendation) has value.

I would like to avoid generic documentation in this project repository. Instead, the project documentation should reference things like Foundational technologies — Creative Commons Open Source.

egbadon-victor commented

@TimidRobot this is noted. I would get to work on a sample, send a draft PR, and then get your opinions on what would be considered generic documentation.

  • 👍1