[Debate] Split documentation into each single component.

[stefanotorresi]

I ask this because I'm not aware of any plan about this, but now that we have the sources split, shouldn't we split the docs too? I reckon this would be no easy task, but since the source split was done to ease maintenance, a centralized documentation repo is in contrast with this very aim, and will become cumbersome very quickly for component maintainers.

AFAIK the reason why we had a separate docs repo in the first place, was because the doc sources for every component were a undesirable overhead when downloading/cloning the central repo, but this is obviously a non-issue now.

So, whaddya think?

[Maks3w]

Related https://github.com/zendframework/zend-diactoros/pull/25

[stefanotorresi]

aww, totally missed that!

so, to sum it up, splitting the documentation will be done.

what is up to debate is the toolchain, and how, when and in what form the docs should be shipped with the components.

@weierophinney proposed bookdown. The main point for it is that it would allow developers to browse the docs of any given component offline, while also allowing to have a central repo that compiles each component docs into a full manual. All this while using just PHP and Markdown, which don't need any tool that a user is not necessarily familiar with (which is arguably not the case for the current RST toolchain).

I personally find this solution very promising. I like the ability to either browse the docs quickly by glancing at a markdown file (either offline or in github), or browse them offline after compiling in HTML via a straightforward PHP cli command.

I also think that the markdowns should be provided with the components regardless (so /docs should not be export-ignored via .gitattributes).

Lastly, I think compiled docs should be committed in the repo only if we opt for github pages.

[weierophinney]

@stefanotorresi I opened the PR on Diactoros:

• Because I wanted to demonstrate how documentation might look inside a component.
• Because that component had no history, and thus no expectations, for documentation.

This repo, however, has a lot of history, and no code. :)

Now that discussion has died down, I'm also talking with @GeeH, as he has volunteered to assist with documentation, particularly during this early phase of the split components. I'll update this post soon wiht details of that discussion.

[weierophinney]

Our consensus on reviewing the various toolchains is that bookdown satisfies the largest set of requirements:

• Documentation in the component repositories. This allows enforcing that new features cannot be merged until documentation is written, and provides the documentation where it contextually makes sense.
• It uses markdown, which is sufficiently easy to learn, and prevalent enough (used on GitHub, StackOverflow, Reddit, Slack, etc.) that most developers will not need to learn a new syntax at all. This is not true of reStructured Text, unfortunately.
• Documentation may be previewed on github as part of the pull request to validate semantic structure and/or as a general resource, without requiring rendering elsewhere. GitHub also provides excellent tools for diffing two markdown sources, making
• It's completely PHP based, meaning no extra development requirements for contributors beyond PHP and Composer (both are used to install, and PHP is used to execute).
• It provides flexible, and — more importantly — simple mechanisms for templating.
• It provides a mechanism for aggregating docs from multiple repositories to create a single manual.
• It does not preclude usage of CI tools. The information in a bookdown.json file can be easily converted to the rtfd.org configuration format in order to allow rendering docs on that platform, if desired.

Among the objections/concerns raised was whether or not we can accommodate things like syntax highlighting of code samples, and, in particular, adding line numbers and/or line highlights. Bookdown does not do this by default. However, tools like prism.js do, and can be part of the master template for rendering documentation. Since bookdown uses league/commonmark, we can likely even extend the code sample template to pull in information such as lines to highlight to include in the generated HTML.

Pandoc can convert from rst to github-flavored markdown already as well, which provides a relatively easy migration tool.

Our plans at this point:

• Create a set of guidelines/standards for the documentation.
• Convert the docs for each component from rst to markdown, and review them for structural elements.
• Generate a bookdown.json file for each component.
• Issue pull requests against each component with the docs relevant to the component.
• Convert the tutorials and push them to a common "top-level"/general documentation repository; have that bookdown.json file contain references to each component.

Gary has volunteered to do the initial steps, in part to help enforce initial consistency of the documentation.

[GeeH]

:+1:

[Maks3w]

Where will be hosted the HTML version?

[GeeH]

It's not confirmed yet but will be hosted by Zend somewhere.

[froschdesign]

Where will be hosted the HTML version?

In the same place as always: http://framework.zend.com/manual

Version 2.4 is a LTS release and the docs can be found at framework.zend.com (up to 2018). Why a different place for the next versions?

[Maks3w]

I wonder if will be some kind of continuos deployment so each merge automatically publish a new rendered version