Unfortunately, what seems to happen as users (and developers) get more in tune with software projects, we forget what is and isn't common knowledge. Perhaps said "wall of text" should be a glossary of terms. A definition list, something that can be open in one tab, and define any ceph-specific or domain-specific terms. Maybe linking back to the glossary for any specific instance of that term. Maybe there should be a glossary per topic, as cephfs has its own set of domain-specific language that isn't necessarily any use to those using rbd. Comment systems are great, until you need people to moderate them, and then that takes time away from people that could either be developing the software or updating documentation. On Thu, Feb 25, 2016 at 11:24 PM, Nigel Williams <nigel.d.williams@xxxxxxxxx> wrote: > On Fri, Feb 26, 2016 at 4:09 PM, Adam Tygart <mozes@xxxxxxx> wrote: >> The docs are already split by version, although it doesn't help that >> it isn't linked in an obvious manner. >> >> http://docs.ceph.com/docs/master/rados/operations/cache-tiering/ > > Is there any reason to keep this "master" (version-less variant) given > how much confusion it causes? > > I think I noticed the version split one time back but it didn't lodge > in my mind, and when I looked for something today I hit the "master" > and there were no hits for the version (which I should have been > looking at). > > I'd be glad to contribute to the documentation effort. For example I > would like to be able to ask questions around the terminology that is > scattered through the documentation that I think needs better > explanation. I'm not sure if pull-requests that try to annotate what > is there would mean some parts would become a wall of text whereas the > explanation would be better suited as a (more informal) comment-thread > at the bottom of the page that can be browsed (mainly by beginners > trying to navigate an unfamiliar architecture). > _______________________________________________ > ceph-users mailing list > ceph-users@xxxxxxxxxxxxxx > http://lists.ceph.com/listinfo.cgi/ceph-users-ceph.com _______________________________________________ ceph-users mailing list ceph-users@xxxxxxxxxxxxxx http://lists.ceph.com/listinfo.cgi/ceph-users-ceph.com
 |