Approach to content

[PeterJCLaw]

(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:

• they're always as accurate as possible
• they're in a form which people are accustomed to, particularly if they have similar relevant experience
• they provide a level of detail which is interesting the reader without being overly specific or complex
• they make no effort to duplicate per-repo documentation (note: documentation is not limited to just the 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:

• the closer it is to the implementation it documents, then more likely it is to be up to date
• the better suited it is to its audience, the more likely it is to be read and understood

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:

• How we do a release (#15):
  • includes: notes on which repos we "release", how we notify teams, protocol around version numbers
  • excludes: details on how the .deb files are built (since that's better documented either in-repo or just by the code)
• A summary of how the kit software works (#18):
  • includes: notes which which repos make it onto the robots, which repos support them, high level details about how those repos are pulled together and where to find out more about that
  • excludes: details of any of the inner workings of those repos (with the possible exception of an overview of the pi-image repo because it somewhat is the "glue" we're describing), instruction on how to use the published API (since that's covered in the public docs repo)

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.

[Adimote]

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)

[trickeydan]

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.