# Better updated online documentation

**URL:** <https://discourse.julialang.org/t/better-updated-online-documentation/16750>\
**Category:** Community\
**Tags:** documentation\
**Created:** [October 24, 2018, 5:24pm UTC](https://discourse.julialang.org/t/better-updated-online-documentation/16750 "2018-10-24T17:24:24Z")\
**Posts on this page:** 11\
**Page:** 1

<div class="post-metadata">

**Author:** ![Vic](https://avatars.discourse-cdn.com/v4/letter/v/9e8a1a/32.png) [@Vic](https://discourse.julialang.org/u/Vic)\
**Post date:** [October 24, 2018, 5:24pm UTC](https://discourse.julialang.org/t/better-updated-online-documentation/16750/1 "2018-10-24T17:24:24Z")

</div>

Currently, the online documentation of the current (stable) Julia version, at [Julia Documentation · The Julia Language](https://docs.julialang.org/en/v1/index.html) , 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](https://docs.julialang.org/en/v1.1-dev/) ) , 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.

---

<div class="post-metadata">

**Author:** ![kristoffer.carlsson](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/kristoffer.carlsson/32/22_2.png) [@kristoffer.carlsson](https://discourse.julialang.org/u/kristoffer.carlsson)\
**Post date:** [October 24, 2018, 5:26pm UTC](https://discourse.julialang.org/t/better-updated-online-documentation/16750/2 "2018-10-24T17:26:17Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![Vic](https://avatars.discourse-cdn.com/v4/letter/v/9e8a1a/32.png) [@Vic](https://discourse.julialang.org/u/Vic)\
**Post date:** [October 24, 2018, 5:29pm UTC](https://discourse.julialang.org/t/better-updated-online-documentation/16750/3 "2018-10-24T17:29:30Z")

</div>

how frequent?

---

<div class="post-metadata">

**Author:** ![kristoffer.carlsson](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/kristoffer.carlsson/32/22_2.png) [@kristoffer.carlsson](https://discourse.julialang.org/u/kristoffer.carlsson)\
**Post date:** [October 24, 2018, 5:33pm UTC](https://discourse.julialang.org/t/better-updated-online-documentation/16750/4 "2018-10-24T17:33:01Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![Vic](https://avatars.discourse-cdn.com/v4/letter/v/9e8a1a/32.png) [@Vic](https://discourse.julialang.org/u/Vic)\
**Post date:** [October 24, 2018, 6:21pm UTC](https://discourse.julialang.org/t/better-updated-online-documentation/16750/5 "2018-10-24T18:21:47Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![Tamas\_Papp](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tamas_papp/32/25949_2.png) [@Tamas\_Papp](https://discourse.julialang.org/u/Tamas_Papp)\
**Post date:** [October 24, 2018, 6:34pm UTC](https://discourse.julialang.org/t/better-updated-online-documentation/16750/6 "2018-10-24T18:34:06Z")

</div>

> [@Vic](#):
>
> Optimal would be at most a couple of days, max tolerable – 1 week.

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.

---

<div class="post-metadata">

**Author:** ![Vic](https://avatars.discourse-cdn.com/v4/letter/v/9e8a1a/32.png) [@Vic](https://discourse.julialang.org/u/Vic)\
**Post date:** [October 24, 2018, 6:38pm UTC](https://discourse.julialang.org/t/better-updated-online-documentation/16750/7 "2018-10-24T18:38:17Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![Tamas\_Papp](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tamas_papp/32/25949_2.png) [@Tamas\_Papp](https://discourse.julialang.org/u/Tamas_Papp)\
**Post date:** [October 24, 2018, 6:56pm UTC](https://discourse.julialang.org/t/better-updated-online-documentation/16750/8 "2018-10-24T18:56:39Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![Vic](https://avatars.discourse-cdn.com/v4/letter/v/9e8a1a/32.png) [@Vic](https://discourse.julialang.org/u/Vic)\
**Post date:** [October 24, 2018, 8:29pm UTC](https://discourse.julialang.org/t/better-updated-online-documentation/16750/9 "2018-10-24T20:29:13Z")

</div>

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)

```julia-auto
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 🙂

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

---

<div class="post-metadata">

**Author:** ![mortenpi](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mortenpi/32/158_2.png) [@mortenpi](https://discourse.julialang.org/u/mortenpi)\
**Post date:** [October 24, 2018, 9:06pm UTC](https://discourse.julialang.org/t/better-updated-online-documentation/16750/10 "2018-10-24T21:06:49Z")

</div>

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](https://github.com/JuliaLang/julia/issues/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](https://github.com/JuliaLang/julia/blob/master/NEWS.md). I reckon bikeshedding in a pull request how the annotations should be done would help move this forward 🙂

---

<div class="post-metadata">

**Author:** ![Vic](https://avatars.discourse-cdn.com/v4/letter/v/9e8a1a/32.png) [@Vic](https://discourse.julialang.org/u/Vic)\
**Post date:** [October 24, 2018, 11:42pm UTC](https://discourse.julialang.org/t/better-updated-online-documentation/16750/11 "2018-10-24T23:42:31Z")

</div>

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 ✨ (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 🤓 wants to improve the docs.