The Apache website infrastructure is hosted in SVN. There are certain requirements for links.
It would be good to discuss. For example is the content in Markdown, XML, HTML or what? It is not a big deal to conform. I have some experience from moving OpenOffice.org to Apache. Regards. Dave > On Jun 12, 2017, at 4:21 PM, Matteo Merli <[email protected]> wrote: > >> The project will need to have a minimal website. > > A colleague of mine, a technical writer, is going through the existing > documentation, editing, expanding it and re-organizing it a bit. He's also > setting up the script and tools to generate a static website with links to > each version documentation. > > A pull-request will be ready in the next few days. We were also waiting for > the repo to be moved over to the ASF before starting with the website > (because some nomenclature will change, copyright noticies, etc..). > > > On Mon, Jun 12, 2017 at 2:11 PM Dave Fisher <[email protected]> wrote: > >> 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
