Ideas for InstructLab's top-level README.md

[andybraren]

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 ilab CLI 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 ilab locally 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.

[bjhargrave]

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]

Agreed that's what docs.instructlab.ai (https://github.com/instructlab/docs.instructlab.ai) was/is designed to do. We planned to cut all the READMEs down to the minimums and have all the centralized documentation located there.

[beaumorley]

Hi @bjhargrave and @jjasghar. This was a request made to UX to make some simple recommendations to the github readme the users will see on first time use. Which, today, I believe it the readme in this issue? In time for the IBM Conference on Oct 21. I think that whatever we recommend could also apply to the centralized documentation approach?

Also, we have an issue for website improvements as well. instructlab/website#143

[andybraren]

@bjhargrave @jjasghar Fixed the link, and totally agree about slimming down our READMEs while pointing folks to the new Docs site, which @kaedward's edits here do. Happy to turn this into a PR as well! 👍