Better updated online documentation

Community
1

Currently, the online documentation of the current (stable) Julia version, at Julia Documentation · The Julia Language , only gets updated once a new version of Julia gets released
(please correct me if I misunderstand).
This is suboptimal for several reasons

  1. Many (most?) of the changes submitted to the “master” branch are actually relevant to the current (stable ) version of Julia. They add in clarity, and could help many new users of Julia.
    • There are many, many ways in which documentation can be improved even if the Julia language itself and the associated libraries remain unchanged.
  2. It reduces the motivation of users/developers to improve the documentation
    • If changes I make that pertain to current version were shown online, the sooner the better, (not after 1 month or more ), and not mixed with changes that pertain to future version (as it sits now in Home · The Julia Language ) , then it will really help me when consulting the documentation.

So I think we should find a way to submit changes to the current online documentation, separately from the changes that only refer to the future version of Julia. And when releasing the new Julia, all should be merged.

I think the doc changes for the same Julia version will be more frequent than the changes related to new features of Julia.

EDIT: Julia documentation is good, to be sure. But, like any documentation, it can always be improved.

2

Doc changes are backported so they get released in the next patch release which are quite frequent.

1 Like
3

how frequent?

4

Julia 1.0.0 was released 8 Aug and Julia 1.0.1 was released 29 Sep.

5

That too big of an interval, for what I explain in my post.
Optimal would be at most a couple of days, max tolerable – 1 week.
Let’s hear from others as well

6

Note that if you don’t find the the update interval for the online docs tolerable, you always have the option of building it from latest master. Just use make docs.

Hope this helps.

7

As I explained in the post, the “master” doc is not good b/c it mixes in changes for new Julia version as well.
And it’s not just for me, but for all new users of the docs, and contributors to the docs.

8

I guess the major constraint is developer time. If you consider this important, perhaps you could maintain a branch that cherry-picks and backports docs changes.

9

Yes, dev-s’ time is important, and users’ time is as well. Maintaining a main current version, and asking developers to prepare their new-language-related changes, all while not freezing the contribution to the current online version, is just as unfair, as asking users to learn 2 versions of language to cherry pick and distill stuff in the “masters” doc to backport to the current online doc.

I think it’s possible to set up a system that will make possible both groups to make changes to a single branch/document, but with such annotations that will allow the processing software to differentiate the 2 versions of the doc during the build process.

Rough idea:

The whole documentation source may contain 3 kind of parts:

  • Parts common to both versions
  • Parts only relevant to the current version of Julia
  • Parts only relevant to the future version of Julia

The version-specific parts can be annotated with a syntax readable by both human, and machine, by using some special tags/delimiters.
For example: (it’s just the idea, I don’t claim these specific delimiters will work)

This is some common part; no need for special annotation
<c> This is stuff pertaining to the current version
could be multiple lines </c> 
Some more common part
<f> This is stuff pertaining to the future Julia version of documentation
could be multiple lines </f>
Again common stuff

The 3 kinds of parts can be interleaved at any level, even within a single sentence.

And it could be color coded too, in principle

Both groups, interested in updating current or future version, work on that, and borrow stylistic elements from each other.
The building process for current online version will ignore the stuff inside the <f> </f> tags, and vice-versa.

When it’s time to finally release that future version, the processing program will delete the stuff within <c> tags together with tags themselves, and delete the <f> tags (only the tags), so that the documentation starts afresh with only common part present, both online and offline.

Hereon, editing users start adding again parts within <c> and <f> tags, and the process repeats.

Feel free to suggest better ideas :slight_smile:

EDIT: above by “future version of Julia” I meant version that change language (syntax/semantics)…

10

That’s basically the plan already. For the whole 1.x, there will only be a single version of the docs (under the v1/ URL; ref #26825). This implies that we have to maintain annotations for when a feature was introduced or deprecated. At some point, we can hopefully have some automation for this, but at the moment it has to be done manually.

This, in turn, implies that the docs for master will also apply to all the previous 1.x releases. At the moment, no one has annotated the 1.1 changes yet, but there are only a few. I reckon bikeshedding in a pull request how the annotations should be done would help move this forward :slight_smile:

2 Likes
11

Oh, really?! that would be good news, if you indeed agree with the intent of this post.

From the perspective of a simple editor of the documentation:

there’s just 1 main Julia language version: the one we program in via the implementation (“application”) Julia currently recommended for download. I’d simply call that current (or present) version, and correspondingly current(present) version of the documentation.

That editor also knows that development is in progress, and at some point Julia language ( i.e, the syntax and semantics,) will change :sparkles: (not just implementation, which change at every small release/patch etc). That changed, future version of the language I’d simply call future (or next) version, and correspondingly so the version of the documentation that applies to it.

Hence the simple idea I posted above, where the 2 kinds of annotations in an unified documentation source unambiguously indicates for which kind of Julia language (as opposed to implementation): present vs future, the editor :nerd_face: wants to improve the docs.