Opened 2 years ago

Last modified 2 years ago

#6286 accepted task (blessed)

Update the Meta Handbook with useful info

Reported by: tellyworth's profile tellyworth Owned by: renyot's profile renyot
Milestone: Priority: normal
Component: Handbooks Keywords:


The Meta Handbook is almost empty and contains little useful info:

It needs to be updated to add some current info about what the team does, how to get started, and where to find things.

Let's discuss and collect ideas for what to add in this ticket.

Change History (5)

#1 @renyot
2 years ago

I'm thinking that we can start by discussing the chapter topics.
Now the chapter topics are not that clear. It seems not to have a strong connection among different chapters, making it a bit hard to read or come back to search stuff.

I'm considering that we can refer to other handbooks like to find out what works best for the meta handbook from each handbook.
This is something I have in mind roughly for the chapter topics we can change to:

  1. About the Meta Team - Introduction to the team. Useful links to both internal and external pages.
    1. Projects (Existing page) - Detailed info about each project of Meta.
  2. Getting Started
    1. Contribute with Code - Env setup. Code Commit. Open PR, etc.
    2. Contribute with Testing
    3. Contribute with Docs
  3. Advanced - Some advanced topics.
  4. Best practices - Some latest practices we follow or some good advice for contributors.
  5. Reference - Links to pages that help contributors know more and deeper about Meta. e.g., Glossary, Events, Schedule, Related Channels, Info/Knowledge reference, etc.

It seems to me that if we could make the goal and definition of every chapter as clear as possible, we can reduce the duplicated content and have a cleaner docs structure for newcomers to follow and contributors to add more stuff. We can spend more time discussing this.

Last edited 2 years ago by renyot (previous) (diff)

#2 @tellyworth
2 years ago

Using other handbooks (especially core) as a template is a great idea for getting things started. It would make sense to use a similar structure, and some of the introductory content could be similar.

Rather than discuss everything first and publish later, I suspect it's more productive to start very small and build incrementally on it. We can use this ticket for discussion in parallel.

Those sound like good chapter topics as a starting point. Why not create those pages and headings right away, even if it's with a stub that says something like "see #6286 to help contribute content here".

One thing I'd like to get up there soon is links to all the key repositories. Especially those outside of Trac, like:

and all the other meta-related repos that I've forgotten :)

#3 @renyot
2 years ago

  • Owner set to renyot
  • Status changed from new to accepted

#4 @tellyworth
2 years ago

Oh I forgot of course!

The Projects page is probably the best place for those to go:

As we discussed privately, some of those are deprecated, and others have Trac links where they should instead link to GitHub. We could either put the GH projects in a separate section, or add them to the main table and link to GH instead of Trac for those.

It seems a bit odd for Codex to have its own special "other projects" section. I guess that's because it wasn't ever open sourced(!). Perhaps it would make sense to rename that section "deprecated", and move the old unmaintained projects in there.

This ticket was mentioned in Slack in #core-test by costdev. View the logs.

2 years ago

Note: See TracTickets for help on using tickets.