Better process for documentation contributions?

Project Infrastructure Documentation
1

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:

  1. 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
  2. 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.
  3. 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.

1 Like
2

I think Sphinx Quickstart Template — LLVM 18.0.0git documentation has most of the information you’re asking about rst files, but we don’t prominently link it anywhere.

We’re currently planning to transitioning code contributions to github, so expect significant changes to how contributions work in the near future. (See Update on GitHub pull requests .) Once that transition is done, we can look at more automation like you’re suggesting.

1 Like
3

Hello and welcome! I fully agree we can and should improve this process. I don’t think the current instructions are the best. I also can understand it’s challenging to find the right owners for documentation and it’s something we need to improve.

I’d love to get your current perspective on how the current documentation to build the docs worked for you and what challenges you encountered.I’m especially interested you which tools you find unfamiliar in the process.

As for GitHub process, that will come with our switched to GitHub and also a larger discussion about markdown.

1 Like
4

Hi both!

I hadn’t realised the shift to GitHub was so soon and that all of LLVM would be moving, that’s nice to hear. Their process isn’t perfect, but it is much better known.

Re: unfamiliar tools:

The thing I spent most time on was figuring out how to build the docs. I lost a while because I didn’t realise I needed to capitalise Ninja for cmake, more time because I didn’t realise I should delete the build dir and start from scratch if cmake failed and I wanted to change the options to fix it, and then a while longer searching for how to actually build the docs, ideally without building all of LLVM first because that’s pretty slow.

I’ve used cmake and ninja before, but not for a while and I kinda hate C/C++ build tools for being slow and confusing and taking dependencies on all system libraries and stuff.

The instructions Eli linked would have made this process much faster if I had found them. I think it would be fine to have cmake match the generator name case insensitively, too. If sphinx doesn’t depend on the cmake config then a script to run it separately might be welcome too, though cmake would obviously have been less painful for me if I had found the correct invocation immediately.

It might have been nice if I had to install fewer system dependencies, too. E.g. why not have the build system set up a virtualenv automatically and keep all the python stuff in there if there isn’t a suitable sphinx installed? This wasn’t really a problem for me building on sorta-old Ubuntu 22.04, but this kind of thing has been a huge waste of time and effort for me when building older software on newer systems or vice versa.

I lost a bit more time finding the syntax to add a link with a custom title to the rst. The syntax is fine, I just didn’t know if the file was built with sphinx or some other dialect of rst so I wasted more time searching than I needed to. Markdown would have been more familiar, but would still need documentation because presumably you’d need to extend it.

I was totally unfamiliar with phabricator and arcanist and the docs are also a bit contradictory about the mailing lists.

I don’t think I spent much time on phabricator. Arcanist was a bit of a pain because the Ubuntu 22.04 package is broken (filed an issue for that too). I spent a short while checking that the tool did what I expected, too.

The final hurdle was finding a suitable reviewer, which took a little while to establish there was no documented owner, and than a while longer to git-blame my way to a suitable person (slower because I did a shallow clone, so I was using the slow blame interface on GitHub).

On Fri, 25 Aug 2023, 07:09 Tanya Lattner via LLVM Discussion Forums, <notifications@llvm.discoursemail.com> wrote:

tonic
August 25

Hello and welcome! I fully agree we can and should improve this process. I don’t think the current instructions are the best. I also can understand it’s challenging to find the right owners for documentation and it’s something we need to improve.

I’d love to get your current perspective on how the current documentation to build the docs worked for you and what challenges you encountered.I’m especially interested you which tools you find unfamiliar in the process.

As for GitHub process, that will come with our switched to GitHub and also a larger discussion about markdown.

Visit Topic or reply to this email to respond.

To unsubscribe from these emails, click here.