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. > 2.3) https://en.wikipedia.org/wiki/Ceph_(software)#History is good but is off site. 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@xxxxxxxxx> 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@xxxxxxxxx. > > This message will be sent to dev@xxxxxxx 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@xxxxxxx > To unsubscribe send an email to dev-leave@xxxxxxx -- Regards Kefu Chai _______________________________________________ Dev mailing list -- dev@xxxxxxx To unsubscribe send an email to dev-leave@xxxxxxx
