On Fri, Feb 26, 2016 at 5:53 AM, Christian Balzer <chibi@xxxxxxx> wrote: > > Hello, > > On Thu, 25 Feb 2016 23:09:52 -0600 Adam Tygart 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/ >> >> http://docs.ceph.com/docs/hammer/rados/operations/cache-tiering/ >> > Indeed, but besides finding it, somebody going explicitly to the Hammer > version would be be foiled by the fact that is has NOT been updated like > master to reflect the need for setting absolute cache sizes. > Which at best would be confusing during tests and at worst in production > is liable to run your cluster into the ground... > >> Updating the documentation takes a lot of effort by all involved, and >> in a project this size, it probably needs a team of people. From what >> I can tell, all the documentation is in the ceph source tree, and >> submitting pull requests/tickets is probably a good option to keep it >> up to date. From my perspective it is also our failure (the users), >> not updating the docs when we run into issues. >> > I have a feeling some dedicated editors including knowledgeable and vetted > volunteers would do a better job that just spamming PRs, which tend to be > forgotten/ignored by the already overworked devs. They're actually pretty easy to review generally, because they don't require as much testing as code changes. I can't see any stale documentation PRs in github at the moment (https://github.com/ceph/ceph/labels/documentation). So I'd say documentation PRs are really quite welcome, don't hesitate to send them. John > > Christian > >> -- >> Adam >> >> On Thu, Feb 25, 2016 at 10:59 PM, Nigel Williams >> <nigel.d.williams@xxxxxxxxx> wrote: >> > On Fri, Feb 26, 2016 at 3:10 PM, Christian Balzer <chibi@xxxxxxx> >> > wrote: >> >> >> >> Then we come to a typical problem for fast evolving SW like Ceph, >> >> things that are not present in older versions. >> > >> > >> > I was going to post on this too (I had similar frustrations), and >> > would like to propose that a move to splitting the documentation by >> > versions: >> > >> > OLD >> > http://docs.ceph.com/docs/master/rados/operations/cache-tiering/ >> > >> > >> > NEW >> > http://docs.ceph.com/docs/master/hammer/rados/operations/cache-tiering/ >> > >> > http://docs.ceph.com/docs/master/infernalis/rados/operations/cache-tiering/ >> > >> > http://docs.ceph.com/docs/master/jewel/rados/operations/cache-tiering/ >> > >> > and so on. >> > >> > When a new version is started, the documentation should be 100% cloned >> > and the tree restructured around the version. It could equally be a >> > drop-down on the page to select the version. >> > >> > Postgres for example uses a similar mechanism: >> > >> > http://www.postgresql.org/docs/ >> > >> > Note the version numbers are embedded in the URL. I like their >> > commenting mechanism too as it provides a running narrative of changes >> > that should be considered as practice develops around things to do or >> > avoid. >> > >> > Once the documentation is cloned for the new version, all the >> > inapplicable material should be removed and the new features/practice >> > changes should be added. >> > >> > >> > >> > _______________________________________________ >> > ceph-users mailing list >> > ceph-users@xxxxxxxxxxxxxx >> > http://lists.ceph.com/listinfo.cgi/ceph-users-ceph.com >> > >> > > > -- > Christian Balzer Network/Systems Engineer > chibi@xxxxxxx Global OnLine Japan/Rakuten Communications > http://www.gol.com/ > _______________________________________________ > 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
 |