Hi - The project will need to have a minimal website. I would be willing to be the test case about documentation. If it is enough for me to understand how to do development and use along with understanding the architecture then it will be good.
I would recommend that a Wiki be used for shared design. There are many approaches and some choices for the Wiki. Apache offers Confluence and MOIN. Then there is Github. I am familiar with Confluence, but don’t let that influence the project’s choice unduly. Here to help. Regards, Dave > On Jun 12, 2017, at 12:55 PM, Matteo Merli <[email protected]> wrote: > >> Is there specific criteria for determining whether documents are > necessary or not? > > That's a good question. I don't have a precise answer for it. As Andrews > stated, it should > allow any contributor to understand the new feature/changes, enough to be > able to > do a meaningful code review and also serve as design documentation for > future > contributors. > > So, if after the discussion, some details are changed, the wiki should be > updated to > reflect the final state. > > If one thinks that additional context is not required, he should go ahead > with a PR. And > later we can discuss whether a design doc for that change would be > beneficial or not. > > For candidates, and to give an example, I was thinking to start with a > "Pulsar native proxy" > proposal that I'm working on. Also, I think other good candidates would be > the > non-persistent topics from Rajan, or the delivery throttling. > > > > On Thu, Jun 8, 2017 at 10:21 PM Sahaya Andrews <[email protected]> > wrote: > >> On Thu, Jun 8, 2017 at 7:08 PM, Nozomi Kurihara <[email protected]> >> wrote: >>> Hi Matteo, >>> >>> ➢ The document doesn't need to be a super-detailed specification, but >> should >>> ➢ explain all the design points, reasons for choosing a determined >> solution, >>> ➢ rejected alternatives and allow for other contributors to >> understand the >>> ➢ feature/change and to contribute as well to it. >>> ➢ >>> I agree with creating such design documents in the Wiki. >>> >>> ➢ for large code changes (new features, improvements) >>> ➢ >>> Is there specific criteria for determining whether documents are >> necessary or not? >> >> One way to approach is how quickly someone new can understand the >> architecture or a feature, so they can contribute back. >> >> Coming up with a list of such modules/features is not difficult. >> >> Andrews. >> >>> >>> Thanks, >>> Nozomi Kurihara >>> >>> 2017/06/09 5:13 に、"Matteo Merli" <[email protected]> を書き込みました: >>> >>> So far the discussion for large code changes (new features, >> improvements) >>> in the project has happened in a very informal way. >>> >>> As a way to improve community involvement and also to have a better >>> internal >>> documentation I would like to propose to adopt the PIP model that >> many >>> projects >>> follow. >>> >>> Here, PIP would stand for "Pulsar Improvement Proposal" and would >> consist >>> in creating design documents in the Wiki with a sequential id. >>> >>> The document doesn't need to be a super-detailed specification, but >> should >>> explain all the design points, reasons for choosing a determined >> solution, >>> rejected alternatives and allow for other contributors to understand >> the >>> feature/change and to contribute as well to it. >>> >>> The advantage would be to have a preliminary discussion and gather >> feedback >>> on the design itself and also have the proposals there as a >> reference. >>> >>> In some cases the design has been discussed over "issues" or PRs but >> then >>> later it's more difficult to understand the whole picture, since the >>> information is fragmented. >>> >>> Opinions? >>> >>> Matteo >>> >>> >>> >>> >>
signature.asc
Description: Message signed with OpenPGP
