hi Zac,
i came across a PR to improve our quick-start-preflight.rst, see
https://github.com/ceph/ceph/pull/32966.
at first glance, i didn't really get the rationale of that change. but
with Tim's reply. i found that we were trying to attack a bigger
problem. i think it's all about usability and accessibility of the
document and packages.
i am copying his PR, comment and my inlined reply here as well so
readers of this mail do not need to leave their MUAs for reading them:
the PR:
====== 8< =====
diff --git a/doc/start/quick-start-preflight.rst
b/doc/start/quick-start-preflight.rst
index b1fdc92d2286..fe09ec8a0629 100644
--- a/doc/start/quick-start-preflight.rst
+++ b/doc/start/quick-start-preflight.rst
@@ -26,11 +26,9 @@ For Debian and Ubuntu distributions, perform the
following steps:
wget -q -O- 'https://download.ceph.com/keys/release.asc' | sudo apt-key add -
-#. Add the Ceph packages to your repository. Use the command below and
- replace ``{ceph-stable-release}`` with a stable Ceph release (e.g.,
- ``luminous``.) For example::
+#. Add the Ceph packages to your repository. For example::
- echo deb
https://download.ceph.com/debian-{ceph-stable-release}/
$(lsb_release -sc) main | sudo tee /etc/apt/sources.list.d/ceph.list
+ echo deb
https://download.ceph.com/debian-luminous/ $(lsb_release
-sc) main | sudo tee /etc/apt/sources.list.d/ceph.list
#. Update your repository and install ``ceph-deploy``::
====== >8 =====
the comments:
====== 8< =====
1. An example should be run-able, otherwise it'a not an example it's
documentation.
i just realized this. thanks for pointing this out. thought user
should do search-and-replace before applying the commands, but that's
obvious another obstacle we setup in front of the quick start.
2. There is no way for a new / uninformed user to
select anything other than luminous as nothing else is listed on the page.
2.1)
https://docs.ceph.com/docs/mimic/releases/ dose not list any newer options
hmm, we should be able to more than this. currently, we are trying to
host the document at Read the Docs which offer a pop-up menu which can
hopefully allow user to move to other versions of the document. see
https://ceph.readthedocs.io/en/latest/ . but it's still a
working-in-progress.
2.2)
https://download.ceph.com/ does not indicate
indicate what option is a sane choice
yeah, a short note would help. even if it's just a release notes of
the latest stable.
right.
3. Maybe something like $(curl -s
https://versions.ceph.com | grep stable | tail -n 1 | cut 2) could be implemented from the
CI tooling...
yeah. a symbolic-link to the latest release would do the trick.
4. there is a different documentation version for
every release so hard coding luminous in the
https://docs.ceph.com/docs/luminous/start/quick-start-preflight/ link seems reasonable.
it's still misleading as again, that stale document could lead user to
an ancient release. we need to have a visible warning tag or something
to note user that this document is based on an older release. or just
use "stable" link in
download.ceph.com.
Side issue is that new / uninformed users have no idea what version of documentation they
are looking at, The version options should be made clear like
https://www.postgresql.org/docs/current/index.html
====== >8 =====
On Tue, Apr 7, 2020 at 12:06 AM John Zachary Dover <zac.dover(a)gmail.com> wrote:
There is a general documentation meeting called the "DocuBetter Meeting", and
it is held every two weeks. The next DocuBetter Meeting will be on April 08, 2020 at 0830
PST, and will run for thirty minutes. Everyone with a documentation-related request or
complaint is invited. The meeting will be held here:
https://bluejeans.com/908675367
Send documentation-related requests and complaints to me by replying to this email and
CCing me at zac.dover(a)gmail.com.
This message will be sent to dev(a)ceph.io every Monday morning, North American time.
The next DocuBetter meeting is scheduled for:
08 Apr 2020 0830 PST
08 Apr 2020 1630 UTC
09 Apr 2020 0230 AEST
Etherpad:
https://pad.ceph.com/p/Ceph_Documentation
Meeting:
https://bluejeans.com/908675367
Thanks, everyone.
Zac Dover
_______________________________________________
Dev mailing list -- dev(a)ceph.io
To unsubscribe send an email to dev-leave(a)ceph.io
--
Regards
Kefu Chai