Open PeterJCLaw opened 6 years ago
I think what you're saying makes a lot of sense.
The only comment I have is we should shift our balance slightly towards making the docs easier to use, over keeping it up to date. (e.g: It would be a good idea to give a short summary of the repositories just so people have a rough idea of whats what without having to click into each one. They won't change much, and I think the ease of access is beneficial)
I agree with @Adimote that the volunteer docs should have a short summary of the repositories. I have thought of an interesting way to do this that would not require updating in the same way potentially. Will investigate and make a PR.
I also think it would be useful to have a summary of how each repository works on a basic level. Much like the presentations. However, the presentations currently only have the slides, which are not that useful by themselves. Hence I think that we should write information also.
Unless the repo changes drastically, a basic overview shouldn't need updating and can be used in addition to rather than instead of the documentation with the code.
Whilst the SRComp wiki is good, it does not contain enough information for somebody who has little to no knowledge of it (like myself) to use it. Hence I am in favour of more detail than this.
EDIT: Another thought I've just had, I think whilst we have good documentation at the lower level of the code, the higher level documentation (e.g how to make use of it in combination with other software, not just how to set it up) is lacking.
(This follows from my conversation with @trickeydan on #35, there should be enough context here though. It also relates to #18, though might end up apply to other topic areas too; hence separation)
What is the level of (technical) content which we feel is useful in these docs?
As I understand it, these volunteer docs exist primarily to help introduce new volunteers to how SourceBots does things and to our codebase. We want to make that codebase as easy to navigate as possible, without that becoming the primary focus of these docs.
From that premise I suggest we want the following properties of our docs:
README.md
file!)These are based on the premise that if we follow practises common to other communities of engineers that we will both find it easier to get others involved (since they're already familiar with the approach) and make it easier for ourselves to re-use our skills when branching outside SourceBots, for the same reason.
We can observe the following properties of documentation:
With both our properties and the general ones in mind, the way I would expect to think about these docs is that the provide a general overview to SourceBots along with the "glue" information which connects up the various things which we do.
Some concrete examples of my understanding of that are:
.deb
files are built (since that's better documented either in-repo or just by the code)There is a trade-off here that I haven't yet mentioned. It is definitely the case that having all documentation in a single place makes it easier to find things from a single search. However as we already have a separation between public kit-docs and the volunteer docs, and have made the decision not to duplicate the former into the latter, we're already accepting that separation by intent is a better approach than the kitchen-sink alternative. I therefore see this trade-off as one where we have already accepted that some separation will need to happen, which I agree with.
This brings us back to my original question: What is the level of (technical) content which we feel is useful in these docs?
I'd put forward the model outlined above (which is used by many projects, including SRComp) as being a common pattern in software and one which works well.