FYI the Cody docs could be a good source of inspiration for how to document Code Suggestions and the editor extensions.
They support VS Code, JetBrains, and Neovim, so probably face similar challenges as we do with information architecture. E.g. their feature parity page.
https://docs.sourcegraph.com/cody/overview
I'm not sure why I kept avoiding this work. It wasn't particularly complex. Now that I'm more familiar with each of the repos, I've reviewed + compared them to each other, and to the main gitlab repo.
I think for the GitLab CLI we don't keep a changelog because we use the releases page which actually generates the same information that the other extensions keep in the changelog. If there's a way to automate the file to match releases, then fine... but I don't want more work on the CLI just to keep them the same.
We could also do a CHANGELOG.MD in the CLI, but just say "see this other page" and that would be fine.
Flexibility matters here. Every project is different. However, I see some common elements and structure we could ensure are similar across all of the projects:
Introduction area:
Title
Short introduction + GitLab / extension logo.
(badges for tests?)
Then we get into the specific subheadings:
## Version compatibility / ## Minimum supported version / ## Requirements ## Setup ### Extension settings## Features ### Code Suggestions ### Others## Data privacy in this extension # SKIP THIS, PER KAI## Support ## Roadmap Cross-link to CONTRIBUTING## Authors and acknowledgment Cross-link to CONTRIBUTORS## Troubleshooting## Resources## Contributing Cross-link to CONTRIBUTING.MD
We have multiple names for conveying requirements. I lean toward ## Requirements but this opinion is loosely held.
I'm proposing a subheading for data privacy. We don't have this now. Do we have language from Legal we can use? I should not be making it up on my own.
We don't currently link to roadmaps, but it's a common item to include in a README. Should we?
Should badges be in the README, in project configuration, or both?
Review the structure here, and then consider the questions I've added. I welcome substantive answers, "seems sensible", and "not important enough to figure out right now."
I don't know about data-privacy... that feels like a hedge because of the GitLab Duo stuff, but I feel like we should then link to the specific docs for Duo. I'm not sure any of the extensions otherwise have anything nor should we try to craft anything.
I don't know where ROADMAP comes from in any of the extensions... I'd expect that to just point to a list of issues or a direction page vs. something that needs to be updated in all the extensions (seems tedious).
Badges in both seems fine - it depends on how they're consumed which is why they exist that way in some.
I'm fine with the structure of the rest of these things and the ordering makes sense to me.
I noticed that some of the projects themselves don't have a great deal of information. I think we can make this better in a few ways. The output of these fields is shown on the main page of the repository, and filling them out helps us look more professional and polished.
Project information. Each project has a blurb in the www-gitlab-com repo, in data/projects.yml, which we could repurpose.
Topics. It should have a few items, like the languages used, and maybe a few others. I'm not sure what, though.
Badges. Should they be here, in the README, or both?