The first thing I personally look for is general information about a project in its top-level README.md file. Which is exactly what you already have, so that box is checked. (At least technically: See below for some suggestions to make improvements.)
The next thing I look for is developer documentation, typically by looking up the package(s) on docs.rs. Your package is not published, so a docs build will not be available, either.
Well, I'll have to start digging into the source and build the docs myself. I will want to quickly peek at the dependency tree by examining Cargo.toml, and I see three git dependencies that you have also not published (so, they also do not have a docs build).
Running cargo doc:
error: no matching package named `lib_jt` found
location searched: Git repository https://github.com/jtreagan/lib_file.git#620efb18
Oof! I can't build the docs because the dependency tree is incomplete... So, I check the Cargo.toml in GitHub - jtreagan/lib_file: A library of utility functions for working with files. and I see that lib_jt does not exist in the most recent version. Back in the Question-Bank-Creator repo, I can fix the build with cargo update. Now cargo doc builds the documentation correctly.
I do not see any documentation comments in the built docs. The only thing I can learn about the code is from the names of types and function signatures. This is "hard mode" documentation, and I would normally end my engagement here and move on to another project.
Building/running QBC works fine enough (on Windows, at least). There are a number of warnings emitted, which is concerning. But the application itself is running.
When it starts, I see two windows, one with a bright blue background and one that is bright red. Red is usually reserved for errors, and the maximum brightness on the colors strains my eyes. I am also confused by the red window, which is not modal, but floats on its own and can be moved to the background or closed. Do I need it? I have no idea.
I can click around in the menus, and if I decide to close the new windows without answering questions, there are error messages printed to the terminal. And an open-file dialog keeps coming up. It is unclear what it expects me to open. A lot of this is exploratory, rather than reading (or following) the instructions.
This has led me to a few simple suggestions:
-
Using a Cargo workspace will keep all of your dependencies in sync. Maintaining multiple repositories is always very difficult.
-
Writing developer documentation is seen by many to be not a fun task. But I really enjoy it! It helps me clearly think about the code. If I can't explain my code to another person, then I have probably written bad code. It gives me a good opportunity to fix design mistakes.
- Writing good documentation is really difficult, even if I generally enjoy writing docs. There is a certain mindset needed to mentally put yourself in someone else's position. Writing for a new perspective is (I think) what makes really outstanding documentation. Because it helps you put necessary contextual information front-and-center for people who may be unfamiliar with your particular background.
-
Publish your crates (after the documentation is made presentable) so that docs can be readily accessed without requiring clone/build steps.
-
"Getting started" as a collaborator is much easier when there is a plan to follow. Add some issues in GitHub! Add labels like "good first issue" and "help wanted". Then organize these issues into projects that form a roadmap. Even if you can't attract collaborators, at least anyone with interest can see what you plan to do with it. That is often much more information than they can get just by looking at the current state of things.
-
Enable discussions and encourage community involvement!
-
Having every related package under a single workspace really helps here! You really want a single source of truth for all of the feature tracking workflow stuff, not have it spread across multiple repositories. (Unless it really makes sense to have them separate.)
-
Depending on the project, it may have very low engagement or none at all. Prepare for that as well. Don't do too much work on the social parts of project management if you are not in need of them.
-
Clean up the warnings. The first sign of a healthy code base is that nothing needs my attention when it has been built. The second sign is that it is lint-free: run cargo clippy --fix to automatically apply a number of suggestions it has out of the box.
-
Be judicious about application usability. The brightly colored backgrounds can be subdued to instantly make using the app more approachable. Address all of the runtime errors that come up when randomly clicking around in the GUI. Dial in the workflow so that you don't need two disconnected windows that are instantly confusing. Don't open a new window for every user interaction. It's very jarring and takes the user out of their flow state.
I wouldn't do all of these things for all projects. There is a balance to strike between building a community and just having a hobby.
Consider creating announcement threads on a variety of social platforms. I don't personally do this often, and I don't have accounts on many of those platforms. But I will sometimes make an announcement on the This Week in Rust newsletter. (They have a "Calls for Participation" section in each newsletter, like this one. This might be something worth trying when you are building your community. Here is a direct link to the CFP guidelines.)
Finally, I would caution that your project is still clearly in the very early stages, and it will be much more difficult to attract attention until you have paid attention to detail, yourself. More important than even documentation is presentation. Put a few screenshots into the README, add a project logo. If it does something really unique or intriguing, create a video/screencast. Write a blog post about what you are doing and why it matters. If you want people to be excited about what you are offering, be charismatic and show your work or at least make a gambit and promise what is coming soon.
