Further to communications with Software Engineering services at the University, it may be wise to improve our documentation to improve the on-boarding of new users. We can definitely take some pointers from this project: https://metawards.org/index.html
Other suggestions also welcome.
Refer to this snippet email:
From my quick look, I think people may be struggling because there isn't a single overview page of the entire system. Your project understandably spans multiple repositories. This makes it difficult to know where to start when learning the system, or how the different parts fit together. I recommend creating a simple GitHub pages website that provides an overview of the entire StarlingUAS organisation. You can do this by creating a repo called "StarlingUAS.github.io" and then just putting documentation into that repo. Switch on "GitHub pages" and you will then have an overview website at https://starlinguas.github.io.
The best way to write this overview is to put yourself in the position of someone who is completely new to the system, but who does have domain-level knowledge (i.e. knows what robots and drones are, understands domain-level concepts). Write a "quick-start guide" that quickly gets someone started. Then consider writing tutorials that show people how to do different things. The quick-start guide and tutorials can then be used to help on-boarding people in your lab (from whom you will get great feedback) and will also help external users pick up and use your code.
A good example of how we've done that for other projects is here: https://metawards.org. This is a GitHub pages site that documents some software we were involved with, and that includes a quick start guide and a full tutorial.
I agree that multi-platform support is challenging. I was not sure, when reading your docs, what the pre-requisites are for your software? Do I need to install docker and minikube on my computer? It is good to include an "INSTALL.txt" or to include installation guides in your website that provide a step-by-step guide to installation (e.g. https://metawards.org/install). Given your system is composed from mulitple bits of software, it may be worth writing an install guide that covers installing and configuring the entire system.
Yes, we can provide some help with cloud. We have a lot of experience of using and deploying, e.g. kubernetes, but caution that it can be difficult to persuade the university to pay for cloud hosting. Am I right in thinking that you don't need cloud hosting, and that instead you are using kubernetes over a private network formed over the drones, so that you can deploy and manage the docker containers there?
mhl787156
commented
2 years ago
Further to communications with Software Engineering services at the University, it may be wise to improve our documentation to improve the on-boarding of new users. We can definitely take some pointers from this project: https://metawards.org/index.html
Other suggestions also welcome.
Refer to this snippet email: