search

sourcebots / volunteer-docs

Documentation and Information for Volunteers
https://volunteering.sourcebots.co.uk
1 stars 1 forks source link

Add index page for "Tour of Code" #35

Closed trickeydan closed 6 years ago

trickeydan commented 6 years ago

See #18

I have added all currently unarchived repositories in the SourceBots organisation on Github.

I am also aware that "Our Codebase" is perhaps not the most appropriate title for this section, open to suggestions.

The "More Info" column is intended to have links to pages with more information on the repo in the future, but as of yet, these pages have not been created.

PeterJCLaw commented 6 years ago

Somewhat serious question: why is this new page better than https://github.com/sourcebots ? It strikes me that it duplicates information to a location where it's likely to get out of date very much faster without providing any additional value. The additional value it seems to be hoping to provide later appears to be things which should instead be being provided in the READMEs of the individual repos.

Note that I don't think that this is an inherent issue in #18, as I do think there is some high level guidance which would be useful here (see https://github.com/PeterJCLaw/srcomp/wiki for an example of where I'd assume this was headed).

Am I missing something which makes the page as it stands useful?

trickeydan commented 6 years ago

Whilst there is duplicate information here, this page is not intended to contain information. It is an index page to link to further pages containing detailed information about how the components of our stack work. For example, it would be bad practice to include detailed information about the internals of robotd in the README for that repository. The volunteer docs exists to explain the more complex internals of our code, rather than just how to use it. Additionally, there are still repositories in the SourceBots organisation that do not have README documents, or indeed information on how to use them. In order to decrease the duplication of information, the child pages of this section should link to the README files in order to explain how to use them, whilst the actual pages explain how the modules work. For example, information similar to the presentations that Andy has recently been giving at meetings. The eventual intention for this page is similar to the wiki that you have linked to, although the detail will be on the child pages. This page is still work in progress, hence the inclusion of the banner which states as such. Merging it has opened up the ability for others to work on the pages below it.

PeterJCLaw commented 6 years ago

For example, it would be bad practice to include detailed information about the internals of robotd in the README for that repository.

While I somewhat agree with this statement, I think you're implying that those details should instead be in the volunteer docs which I definitely disagree with. Documentation for any code should be as close to that code as is reasonably practical; the chances that documentation will get out of date are proportional to their distance from the code.

The level of information which I see as being useful separate from the code repos themselves is that describing how to combine our projects -- this would be akin to information based on their public APIs, which are reasonable to expect are stable over the medium term.

trickeydan commented 6 years ago

I will create a separate pull request to create a page for robotd (from my limited knowledge of it, and in an attempt to gain a greater understanding of it). This should help consolidate the scope of this section of the docs.