bjhargrave
commented
3 hours ago I think this is interesting but we should focus on fleshing out and improving the docs.instructlab.ai website instead of investing in continuing to use the READMEs as a documentation provider.
I would think the org readme should provide a quick overview and point onwards to the docs website for more detailed information which is improved as per your observations.
cc: @jjasghar
Here's a document where we've started to iterate on a draft that incorporates the ideas listed below.
Also, non-Red Hatters cannot read this doc.
jjasghar
beaumorley
A few designers at Red Hat have been investigating InstructLab's onboarding experience for newcomers, and we've identified a few potential improvement ideas for the top-level README.md file.
Here's a document where we've started to iterate on a draft that incorporates the ideas listed below.
We're curious to hear what the community thinks of these ideas, and other ways to make onboarding to the project even easier for newcomers!
Suggestions
1) Streamline the steps to get started
The "Get Started with InstructLab" section currently suggests 6 possible next steps with equal weight. Visitors to this GitHub page seem more likely than most to want quick access to the
ilabCLI so that they can start kicking the tires before deciding to engage with the community more deeply.Recommendation Provide a more guided step-by-step path that starts with pointing to a definitive set of instructions to install InstructLab locally*, then ways to contribute knowledge/skills to the taxonomy, and finally how to engage with the community to ask for help or contribute in other ways (pointing to the community README).
*note: there seem to be a few different places with instructions to set up
ilablocally today, including a Quick Start, the Docs site, and the ilab README. There might be an opportunity to consolidate some of these to provide a more prescriptive path for new users and reduce the community's maintenance burden.2) Focus on key quick links
The "Quick Links" section includes links that may not be the most top-of-mind for new visitors, and its position near the bottom of the page makes it more difficult to discover quickly. As the top-level README for the project, we should include links that newcomers are most likely to be interested in and place them prominently near the top where they can be more easily found.
Recommendation Move this section closer to the top of the README and provide key links to the new Docs site, the CLI instructions, Hugging Face, the community Slack & calendar, and social channels (YouTube, X, etc.).
3) Consolidate information and pathways
For example, "Community Meetings" are one of many potential ways to engage with the community that's covered by a separate Community-focused README. There are a few other instances where lower-level information and links can be covered elsewhere, and let the top-level README serve as more of a directory instead.
Recommendation Remove the "Community Meetings" section. Visitors interested in getting involved in the community can use the link to the Community README in the revised "Get Started" section.