updating the documentation

updating the documentation

[Sage Weil]

We have a fair-sized list of documentation items to update for the 
luminous release.  The other day when I starting looking through what is 
there now, though, I was also immediately struck by how out of date much 
of the content is.  In addition to addressing the immediate updates for 
luminous, I think we also need a systematic review of the current docs 
(including the information structure) and a coordinated effort to make 
updates and revisions.

First question is, of course: is anyone is interested in helping 
coordinate this effort?

In the meantime, we can also avoid making the problem worse by requiring 
that all pull requests include any relevant documentation updates.  This 
means (1) helping educate contributors that doc updates are needed, (2) 
helping maintainers and reviewers remember that doc updates are part of 
the merge criteria (it will likely take a bit of time before this is 
second nature), and (3) generally inducing developers to become aware of 
the documentation that exists so that they know what needs to be updated 
when they make a change.

Comments or concerns?

Thanks!
sage

Re: updating the documentation

[Patrick Donnelly]

On Wed, Jul 12, 2017 at 11:29 AM, Sage Weil <sweil@redhat.com> wrote:
> In the meantime, we can also avoid making the problem worse by requiring
> that all pull requests include any relevant documentation updates.  This
> means (1) helping educate contributors that doc updates are needed, (2)
> helping maintainers and reviewers remember that doc updates are part of
> the merge criteria (it will likely take a bit of time before this is
> second nature), and (3) generally inducing developers to become aware of
> the documentation that exists so that they know what needs to be updated
> when they make a change.

There was a joke to add a bot which automatically fails PRs for no
documentation but I think there is an way to make that work in a
reasonable way. Perhaps the bot could simply comment on all PRs
touching src/ that documentation is required and where to look, and
then fails a doc check. A developer must comment on the PR to say it
passes documentation requirements before the bot changes the check to
pass.

This addresses all three points in an automatic way.

-- 
Patrick Donnelly

Re: updating the documentation

[Piotr Dałek]

On Wed, Jul 12, 2017 at 11:37:32AM -0700, Patrick Donnelly wrote:
> On Wed, Jul 12, 2017 at 11:29 AM, Sage Weil <sweil@redhat.com> wrote:
> > In the meantime, we can also avoid making the problem worse by requiring
> > that all pull requests include any relevant documentation updates.  This
> > means (1) helping educate contributors that doc updates are needed, (2)
> > helping maintainers and reviewers remember that doc updates are part of
> > the merge criteria (it will likely take a bit of time before this is
> > second nature), and (3) generally inducing developers to become aware of
> > the documentation that exists so that they know what needs to be updated
> > when they make a change.
> 
> There was a joke to add a bot which automatically fails PRs for no
> documentation but I think there is an way to make that work in a
> reasonable way. Perhaps the bot could simply comment on all PRs
> touching src/ that documentation is required and where to look, and
> then fails a doc check. A developer must comment on the PR to say it
> passes documentation requirements before the bot changes the check to
> pass.

For sure it could fail if a PR changes config_opts.h and doesn't carry any
doc update -- lack of docs for config options is probably the most common
and most annoying issue among Ceph users.

-- 
Piotr Dałek
branch@predictor.org.pl
http://blog.predictor.org.pl

Re: updating the documentation

[Sage Weil]

On Wed, 12 Jul 2017, Patrick Donnelly wrote:
> On Wed, Jul 12, 2017 at 11:29 AM, Sage Weil <sweil@redhat.com> wrote:
> > In the meantime, we can also avoid making the problem worse by requiring
> > that all pull requests include any relevant documentation updates.  This
> > means (1) helping educate contributors that doc updates are needed, (2)
> > helping maintainers and reviewers remember that doc updates are part of
> > the merge criteria (it will likely take a bit of time before this is
> > second nature), and (3) generally inducing developers to become aware of
> > the documentation that exists so that they know what needs to be updated
> > when they make a change.
> 
> There was a joke to add a bot which automatically fails PRs for no
> documentation but I think there is an way to make that work in a
> reasonable way. Perhaps the bot could simply comment on all PRs
> touching src/ that documentation is required and where to look, and
> then fails a doc check. A developer must comment on the PR to say it
> passes documentation requirements before the bot changes the check to
> pass.
> 
> This addresses all three points in an automatic way.

This is a great idea.  Greg brought up the idea of a bot but we 
didn't think of a "docs ok"-type comment to make it happy.

Anybody interested in coding it up?

Piotr makes a good point about config_opts.h, although that problem is 
about to go away (or at least change) with John's config update:

	https://github.com/ceph/ceph/pull/16211

(Config options will be documented in the code where the schema is 
defined, and docs.ceph.com .rst will eventually be auto-generated from 
that.)

sage

Re: updating the documentation

[John Spray]

On Wed, Jul 12, 2017 at 8:28 PM, Sage Weil <sweil@redhat.com> wrote:
> On Wed, 12 Jul 2017, Patrick Donnelly wrote:
>> On Wed, Jul 12, 2017 at 11:29 AM, Sage Weil <sweil@redhat.com> wrote:
>> > In the meantime, we can also avoid making the problem worse by requiring
>> > that all pull requests include any relevant documentation updates.  This
>> > means (1) helping educate contributors that doc updates are needed, (2)
>> > helping maintainers and reviewers remember that doc updates are part of
>> > the merge criteria (it will likely take a bit of time before this is
>> > second nature), and (3) generally inducing developers to become aware of
>> > the documentation that exists so that they know what needs to be updated
>> > when they make a change.
>>
>> There was a joke to add a bot which automatically fails PRs for no
>> documentation but I think there is an way to make that work in a
>> reasonable way. Perhaps the bot could simply comment on all PRs
>> touching src/ that documentation is required and where to look, and
>> then fails a doc check. A developer must comment on the PR to say it
>> passes documentation requirements before the bot changes the check to
>> pass.
>>
>> This addresses all three points in an automatic way.
>
> This is a great idea.  Greg brought up the idea of a bot but we
> didn't think of a "docs ok"-type comment to make it happy.
>
> Anybody interested in coding it up?
>
> Piotr makes a good point about config_opts.h, although that problem is
> about to go away (or at least change) with John's config update:
>
>         https://github.com/ceph/ceph/pull/16211
>
> (Config options will be documented in the code where the schema is
> defined, and docs.ceph.com .rst will eventually be auto-generated from
> that.)


Separate to the discussion of bots, here's a proposed change to the
SubmittingPatches.rst to formalize the expectation that submitters
make doc changes in their PRs.

The twist here is that in addition to requiring submitters to make
changes, there is a responsibility on the component tech leads to
ensure there is a proper place for doc changes to go.  That means that
if someone comes with a change to a completely undocumented area of
functionality, then it is not the submitter's responsibility to create
the whole page just to note their small change (although it would
obviously be awesome if they did).

Cheers,
John

> sage
> --
> To unsubscribe from this list: send the line "unsubscribe ceph-devel" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [ceph-users] updating the documentation

[Gregory Farnum]

On Tue, Jul 18, 2017 at 6:51 AM, John Spray <jspray@redhat.com> wrote:
> On Wed, Jul 12, 2017 at 8:28 PM, Sage Weil <sweil@redhat.com> wrote:
>> On Wed, 12 Jul 2017, Patrick Donnelly wrote:
>>> On Wed, Jul 12, 2017 at 11:29 AM, Sage Weil <sweil@redhat.com> wrote:
>>> > In the meantime, we can also avoid making the problem worse by requiring
>>> > that all pull requests include any relevant documentation updates.  This
>>> > means (1) helping educate contributors that doc updates are needed, (2)
>>> > helping maintainers and reviewers remember that doc updates are part of
>>> > the merge criteria (it will likely take a bit of time before this is
>>> > second nature), and (3) generally inducing developers to become aware of
>>> > the documentation that exists so that they know what needs to be updated
>>> > when they make a change.
>>>
>>> There was a joke to add a bot which automatically fails PRs for no
>>> documentation but I think there is an way to make that work in a
>>> reasonable way. Perhaps the bot could simply comment on all PRs
>>> touching src/ that documentation is required and where to look, and
>>> then fails a doc check. A developer must comment on the PR to say it
>>> passes documentation requirements before the bot changes the check to
>>> pass.
>>>
>>> This addresses all three points in an automatic way.
>>
>> This is a great idea.  Greg brought up the idea of a bot but we
>> didn't think of a "docs ok"-type comment to make it happy.
>>
>> Anybody interested in coding it up?
>>
>> Piotr makes a good point about config_opts.h, although that problem is
>> about to go away (or at least change) with John's config update:
>>
>>         https://github.com/ceph/ceph/pull/16211
>>
>> (Config options will be documented in the code where the schema is
>> defined, and docs.ceph.com .rst will eventually be auto-generated from
>> that.)
>
>
> Separate to the discussion of bots, here's a proposed change to the
> SubmittingPatches.rst to formalize the expectation that submitters
> make doc changes in their PRs.

https://github.com/ceph/ceph/pull/16394 was meant to go here, I think. :)
-Greg

>
> The twist here is that in addition to requiring submitters to make
> changes, there is a responsibility on the component tech leads to
> ensure there is a proper place for doc changes to go.  That means that
> if someone comes with a change to a completely undocumented area of
> functionality, then it is not the submitter's responsibility to create
> the whole page just to note their small change (although it would
> obviously be awesome if they did).
>
> Cheers,
> John
>
>> sage
>> --
>> To unsubscribe from this list: send the line "unsubscribe ceph-devel" in
>> the body of a message to majordomo@vger.kernel.org
>> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> _______________________________________________
> ceph-users mailing list
> ceph-users@lists.ceph.com
> http://lists.ceph.com/listinfo.cgi/ceph-users-ceph.com

Re: [ceph-users] updating the documentation

[John Spray]

On Tue, Jul 18, 2017 at 9:03 PM, Gregory Farnum <gfarnum@redhat.com> wrote:
> On Tue, Jul 18, 2017 at 6:51 AM, John Spray <jspray@redhat.com> wrote:
>> On Wed, Jul 12, 2017 at 8:28 PM, Sage Weil <sweil@redhat.com> wrote:
>>> On Wed, 12 Jul 2017, Patrick Donnelly wrote:
>>>> On Wed, Jul 12, 2017 at 11:29 AM, Sage Weil <sweil@redhat.com> wrote:
>>>> > In the meantime, we can also avoid making the problem worse by requiring
>>>> > that all pull requests include any relevant documentation updates.  This
>>>> > means (1) helping educate contributors that doc updates are needed, (2)
>>>> > helping maintainers and reviewers remember that doc updates are part of
>>>> > the merge criteria (it will likely take a bit of time before this is
>>>> > second nature), and (3) generally inducing developers to become aware of
>>>> > the documentation that exists so that they know what needs to be updated
>>>> > when they make a change.
>>>>
>>>> There was a joke to add a bot which automatically fails PRs for no
>>>> documentation but I think there is an way to make that work in a
>>>> reasonable way. Perhaps the bot could simply comment on all PRs
>>>> touching src/ that documentation is required and where to look, and
>>>> then fails a doc check. A developer must comment on the PR to say it
>>>> passes documentation requirements before the bot changes the check to
>>>> pass.
>>>>
>>>> This addresses all three points in an automatic way.
>>>
>>> This is a great idea.  Greg brought up the idea of a bot but we
>>> didn't think of a "docs ok"-type comment to make it happy.
>>>
>>> Anybody interested in coding it up?
>>>
>>> Piotr makes a good point about config_opts.h, although that problem is
>>> about to go away (or at least change) with John's config update:
>>>
>>>         https://github.com/ceph/ceph/pull/16211
>>>
>>> (Config options will be documented in the code where the schema is
>>> defined, and docs.ceph.com .rst will eventually be auto-generated from
>>> that.)
>>
>>
>> Separate to the discussion of bots, here's a proposed change to the
>> SubmittingPatches.rst to formalize the expectation that submitters
>> make doc changes in their PRs.
>
> https://github.com/ceph/ceph/pull/16394 was meant to go here, I think. :)

Correct!  I like to throw the mistakes out there every once in a while
to check someone is paying attention :-)

John

> -Greg
>
>>
>> The twist here is that in addition to requiring submitters to make
>> changes, there is a responsibility on the component tech leads to
>> ensure there is a proper place for doc changes to go.  That means that
>> if someone comes with a change to a completely undocumented area of
>> functionality, then it is not the submitter's responsibility to create
>> the whole page just to note their small change (although it would
>> obviously be awesome if they did).
>>
>> Cheers,
>> John
>>
>>> sage
>>> --
>>> To unsubscribe from this list: send the line "unsubscribe ceph-devel" in
>>> the body of a message to majordomo@vger.kernel.org
>>> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>> _______________________________________________
>> ceph-users mailing list
>> ceph-users@lists.ceph.com
>> http://lists.ceph.com/listinfo.cgi/ceph-users-ceph.com

Re: updating the documentation

[Dan Mick]

On 07/12/2017 11:29 AM, Sage Weil wrote:
> We have a fair-sized list of documentation items to update for the 
> luminous release.  The other day when I starting looking through what is 
> there now, though, I was also immediately struck by how out of date much 
> of the content is.  In addition to addressing the immediate updates for 
> luminous, I think we also need a systematic review of the current docs 
> (including the information structure) and a coordinated effort to make 
> updates and revisions.
> 
> First question is, of course: is anyone is interested in helping 
> coordinate this effort?
> 
> In the meantime, we can also avoid making the problem worse by requiring 
> that all pull requests include any relevant documentation updates.  This 
> means (1) helping educate contributors that doc updates are needed, (2) 
> helping maintainers and reviewers remember that doc updates are part of 
> the merge criteria (it will likely take a bit of time before this is 
> second nature), and (3) generally inducing developers to become aware of 
> the documentation that exists so that they know what needs to be updated 
> when they make a change.

As a reminder, there is a 'needs-doc' tag.  I don't think it's seen much
use and I'm aware of its problems.  Nothing beats discipline.


-- 
Dan Mick
Red Hat, Inc.
Ceph docs: http://ceph.com/docs

Updating the documentation

[Stuart Axon]

Some of the dosemu documentation is pretty old, I've just made some
updates to the howto
http://sourceforge.net/tracker/index.php?func=detail&aid=1692299&group_id=49784&atid=457449

There were a couple of things I wasn't sure about that someone on the
users list might know about so I'm cross-posting my changes here.

Changes:

Since windows up to WFW 3.11 seems to be working and install ok, remove
WINOS2 from the howto as it's no longer needed.

"due to 'Recent changes' some 32 bit games work" -> "some 32 bit games work"
"Newest version as of 2004 is 1.2.0" -> "newest stable version as of 2007 is
1.2.0"


Not changed-
"We just decided to leave BETA stage, however: there may be serious bugs
and very little documentation for new features. The development version
is particularly likely to have bugs. Please use it only if you
like to do active development. Preferably fix bugs in the development
version instead of reporting them."

- I'm sure I've seen advice elsewhere to use the development version,
so maybe this should reflect that?


"1.3. What processors does dosemu work on?

Dosemu only works on Intel 80x86 processors, e.g. 80386, 80486, Pentium
etc."

- I was under the impression that with CPUEMU it could work on other
architectures, but haven't got a way of testing this, if someone has more
information
I'll change this too.