>"Cook, Malcolm" <mailto:MEC@stowers.org> writes:
>
>> The section on org-mode [[https://orgmode.org/org.html#Installation][Installation]] entitled "Using Emacs packaging
>> system" might be improved with the following advice:
>
>Thanks!
>
>> Note: For the upgraded version to be loaded by emacs, you mush place
>> `package-initialize` early in your init.el. Failure to do so will
>> result in the old system version to be loaded, as can be seen:
>
>This is only true when running emacs -Q or emacs -q.
>For normal emacs invocation, since Emacs 27, by default, Emacs calls
>(package-initialize) automatically on startup.
>
>> Note further that if the above upgrade command was done in an emacs
>> shell buffer, you will need to restart emacs to pick up the updated
>> package. Failing to do so will result in `meta-x org-version`
>> reporting the old version:
>>
>> #+begin_src src
>> Org mode version 9.6.15 (release_9.6.15 @ /usr/local/share/emacs/30.0.50/lisp/org/)
>> #+end_src
>>
>> but after restart with my init.el file it reports:
>>
>> #+begin_src src
>> Org mode version 9.6.27 ( @ /home/mec/.dotfiles/emacs/.emacs.d/elpa/org-9.6.27/)
>> #+end_src
>
>Examples are probably a bit too much for the manual.
>It should be sufficient to ask to restart existing Emacs sessions, if
>any.
>
>May you prepare a patch modifying doc/org-manual.org with your suggestions?
>See https://orgmode.org/worg/org-contribute.html

Glad to try.  How's this?