Would make sense to separate the documentation to another repository?

I’m not expert on this. But for me, it would make sense to separate the development of the manual and the documentation from julia to somewhere else. I consider that this would follow the philosophy of the “packages” in stdlib which can be now (I don’t know the exact details) updated without “touching” the julia repository.

UPDATE MOTIVATION: Now that 1.0 is relesed, some more effort could go on this direction. If possible, a better documentation and manual will be better for newcomers.

I have made a few PR’s to the Julia manual in the past few years, and I agree that it would be easier for people who want to contribute to the documentation to be able to create a branch of just the documentation rather than the whole Julia project. But one problem is that a significant percentage of the documentation lives in docstrings that are in-line with the source code itself. There is a strong argument to be made in favor of having the docstring right next to the source code.

2 Likes

Hear, hear. If anything, the docs should be more coupled to the code IMHO :slight_smile:

1 Like

Interesting idea. There is nothing preventing us from moving the markdown docs (i.e. the content of https://github.com/JuliaLang/julia/tree/master/doc) to a separate repository. Docstrings can also be attached from the outside, and does not have to be in the julia repository. But it kinda makes sense to keep the docstrings where they are. This makes it much easier to update code and documentation simultaniously, which seems like a huge advantage.

5 Likes

FWIW, many of the latest commits in the JuliaLang/julia repository are about the documentation.