[RFC] Documentation System and Requirements

[nickvergessen]

... it also means that arduous and unnecessary core development processes must be followed for documentation development (Commit messages, unable to use the github flow, topic branch naming requirements etc.)

We could also lessen that for doc-only PRs

I would support having two repositories and instead having a similar system to Symfony where it is required that a PR exists against the docs repo...

Which conflicts with your first requirement?

You shouldn't need to have to checkout a git repo locally or have to create JIRA issues or know about git branching or rebasing etc.

[Nicofuma]

He means to contribute to the documentation, not to contribute to the core.

There is two kind of contributors here:
- one who work on a feature and should/could also provide the documentation for this feature
- one who work only on the documentation (improvements, fix, translation....)

And we should assume that the second kind of contributor doesn't know anything about git or Github, he wants to be able to clic on the edit button on Github.

[MichaelC]

I would support having two repositories and instead having a similar system to Symfony where it is required that a PR exists against the docs repo...

Which conflicts with your first requirement?

You shouldn't need to have to checkout a git repo locally or have to create JIRA issues or know about git branching or rebasing etc.

And we should assume that the second kind of contributor doesn't know anything about git or Github, he wants to be able to clic on the edit button on Github.

Indeed, the 'Github Flow' can be used by documentation contributors.

[naderman]

Based on this discussion we are in the process of setting up sphinx documentation. It is being created in the 3.1.x and master branches of the existing documentation repository at https://github.com/phpbb/documentation/ ... evelopment. The development directory contains the new developer documentation while the documentation directory contains the existing end user documentation on http://www.phpbb.com.