[RFC] Documentation System and Requirements

[EXreaction]

Currently documentation is added to the phpBB Development Wiki whenever someone feels like there should be documentation.

This leads to a few issues:

• Creating documentation while creating the PR and code is very difficult and not realistic (it's possible the PR may not be accepted as-is and thus documentation would be there for nothing).
• Nobody wants to create documentation after a PR for a feature is merged. The original author is likely to have moved on to other issues and nobody else is likely to do it.
• As features are changed, documentation on the Wiki is not updated to reflect the changes.
• Documentation does not take into account different versions of phpBB (or even identify which version the documentation is for) unless explicitly stated.

So the end result is: We have terrible code/api documentation (none at all in most cases, outdated in most of the remaining cases).

To fix these problems we need to do a few things:

• Move documentation to the phpBB repository so documentation can be created as code is written and documentation is version specific.
• Require API documentation in PRs before they will be accepted

Ideally this would lead to a system such as the one that Symfony has (which, in my opinion, has some of the best documentation of any open source software I've ever used):
http://symfony.com/doc/current/reference/index.html

They use http://docutils.sourceforge.net/rst.html

[imkingdavid]

I agree with the idea overall, but I disagree with using the reStructuredText format, as it is just one more syntax to learn. It is already fairly similar to markdown, from what I can tell, so I say we go with Markdown and convert that to HTML.

What do you propose we do with the wiki?

Does this documentation go into the main phpbb3 repo or in its own repository? If the former, that makes the package just that much larger, but if the latter, that makes it a little more of a hassle because you have to commit to two separate repos.

[MichaelC]

This shouldn't be too hard to implement using sphinx (the parser symfony use), however all existing documentation (from the wiki) would need changing over to RST (which is extremely similar to MD) format. Sphinx supports multiple versions and we can likley set it to automatically update from the github repository which can hold the code documentation.

I'm certainly +1 moving to using Sphinx & repository tracking of code documentation.

You can view information on the symfony documentation here and information on sphinx (the parser) here

I'd suggest that when this is complete, we adopt a similar policy to Symfony of how to treat Pull Requests (requiring a PR with docs ready for merge before merging the main PR) and whilst this is being done, introducing a similar checklist for pull requests that exists in the first post of pull requests:

Code: Select all

| Q             | A
| ------------- | ---
| Bug fix?      | [yes|no]
| New feature?  | [yes|no]
| BC breaks?    | [yes|no]
| Deprecations? | [yes|no]
| Fixed tickets | [comma separated list of tickets fixed by the PR]
| License       | MIT
| Doc PR        | [The reference to the documentation PR if any]

The reason the suggestion for rst came about is because of sphinx, something that already exists to parse the rst files to HTML. It is used by most projects (PPI, Symfony etc.) for documentation and there are extensions for it that mean we can have pages like http://symfony.com/doc/build_errors, have nice syntax highlighting etc. It would be a ridiculously pointless amount of extra work if we had to build a parser for MD. rst is basically like MD but with a few tiny differences, it really isn't worth it.

As for repos, it should be two separate repos, both technically and for organisation. And commiting to two repos isn't exactly a lot more work than working on the wiki and working on the code? You can use the github file editing interface if you don't want to checkout the repository yourself.

[EXreaction]

What format we use isn't extraordinarily important; as long as we can make the output pretty it's fine--something that already exists and requires us to do the least amount of work would be best.

As far as including it in the main repository, I think this is important to make sure we get documentation in PRs and keep documentation up-to-date. The directory can be removed from the package before it's released (just like all the root directories besides phpBB).

[MichaelC]

As far as including it in the main repository, I think this is important to make sure we get documentation in PRs and keep documentation up-to-date. The directory can be removed from the package before it's released (just like all the root directories besides phpBB).

I personally think this will make things less organised (docs PRs/issues vs actual code) and also it means we cannot setup a hook between github and sphinx to generate new docs on all pushes (or we could but it would waste a lot of resources). I believe we should keep docs & code separate (this is what most projects do).

Also it would mean we can only do docs per branch, not per version (sometimes this could be needed for bug fixes or security fixes that require changes to the code documentation [afterall, it is code documentation and the code is being changed in fixes as well as larger improvements/fixes/features]).

With regards to ensuring docs are up-to-date, this is done fine by symfony and other orgs I know of who use the system I said earlier (ensuring there is an up-to-date docs PR before merging the main PR).

[EXreaction]

I'm sure a hook can be designed that only regenerates on changes to a certain folder.

Having it in the existing repository vs external would not make any difference of tracking versions or branches. Branches are made for each version released, so we would have accurate documentation for any version or branch (develop). The only difference is that if it was separate we'd need to handle creating all the branches there as well and manage all that merging throughout different versions on phpbb and documentation rather than just once.

If it's kept separate I'm not sure there are huge advantages to having it in a repository over the Wiki.

[MichaelC]

I'm sure a hook can be designed that only regenerates on changes to a certain folder.

Having it in the existing repository vs external would not make any difference of tracking versions or branches. Branches are made for each version released, so we would have accurate documentation for any version or branch (develop). The only difference is that if it was separate we'd need to handle creating all the branches there as well and manage all that merging throughout different versions on phpbb and documentation rather than just once.

If it's kept separate I'm not sure there are huge advantages to having it in a repository over the Wiki.

True, but we still have to process every push server side.

Branches are not made for each release, just release prep branches & tags.

And the advantage is being able to PR and have it repository tracked no? Also people are more likely to update a PR than a wiki article as it is theirs specifically, has notifications etc.

[Pony99CA]

Couldn't we use something like JavaDoc and extract API documentation from comments in the code itself? During a Pull Request review, if the comments didn't match the API, the PR would be rejected. If a PHP version of JavaDoc doesn't already exist, somebody would have to write a pre-processor, too.

The above only applies to programmer-level documentation, of course; user-level documentation is a different issue.

Steve

[Nicofuma]

Bump

As it was said earlier, nowadays the developer documentation (explaining how things works, how they are designed and how we can use them) is very important if we want to attract more contributors for both the core and the extensions. We can't stay like that.

So to resume the proposal:

• Move the documentation to a /documentation directory at the top of the main phpBB repository (https://github.com/phpbb/phpbb)
• Require the documentation in the PRs (a PR for a new feature should include the documentation for this feature and any PR improving a feature should update the corresponding documentation)

Issues:

• Having to create a ticket to update the documentation each time you want to change a thing (eg: for a misspelled word) is a *little* "boring"

Do you agree? And if yes what should we use? Markdown? RST? Something else? (keep in mind that we will have to parse the documentation and render it as plain html pages so propose couples syntax/parser if possible)

• RST/Sphinx (used by Symfony)
• Extended Markdown/Sculpin (very extensible parser written in PHP and using Twig)

[MichaelC]

This has to have a few points
1) It must be really easy to contribute documentation (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.)
2) It must not make people think "Actually I won't contribute x to phpBB because I have to do docs too and I don't have the effort"
3) It should be maintainable by all relevant teams (Extensions team, Development Team and to some extent other teams such as the Support Team and Styles Team).

The problem with having it in the same repository as phpBB core means only the development team are able to merge things into the documentation and 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.) that we already know put developers off contributing to phpBB on occasion and documentation contributors are more likely to be of a less-technical calibre. Furthermore not all development team members are native English speakers so they aren't even necessarily the best people to be reviewing copy.

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 when a core PR is merged (the docs pr does not need to be complete/finished/merge-ready but it it does need to exist). This also means that we don't need to hold up merging core features due to a lack of documentation in addition to the advantage documentation can be done by other people than the PR submitter. The primary concern we need to have is a valid way to ensure new features/changes are documented and a PR or issue of some sort against the docs repo means that it is at the very least 'on the todo list' and will not be forgotten about.