Summary: I just submitted a tiny change to the LLVM docs and I’d like to make a few larger contributions to them, but the process of doing so took way longer than I wanted. Is there a better process for this? If not, I have some suggestions.
I added a link to a single file and it took me over an hour (maybe 2) because of all the setup, unclear processes, and unfamiliar tools. And, of course, the process isn’t finished because my revision is yet to be reviewed and committed. I expect that the process will be much quicker next time, but it’s obviously a big barrier to entry compared to editing a wiki or fixing docs in most github projects.
Is there a quicker process for submitting doc changes to the LLVM project or getting set up to submit doc changes?
If not, here are some suggestions:
- Explain how to contribute to the docs in the docs. This should be a shorter document than the generic contributing instructions and should cover:
- the github process, if accepting changes through there (see below)
- how to build just the docs
- who to tag for review
- any style guide and best practices for the rst files
- Consider accepting documentation changes through github. An “edit on github” link in the generated docs, a CODEOWNERS file or other process to auto-assign reviewers, and a github action to link the built docs could make this a pretty easy and slick process for casual contributors and reviewers.
- Identify a person or small team of people who are happy to review and commit less-technical changes to the documentation and make them easily selectable as reviewers.
I don’t have much familiarity with this project and obviously no authority within it, so I can’t make progress on points 2 or 3, but I’m happy to write something for point 1 if someone more familiar with the project helps me out with the questions about style guide and who to tag for a review.