Looking for more information on how to do PHP the right way? Check out PHP: The Right Way

Mattias Noback:
Project documentation with Sculpin
Dec 12, 2016 @ 09:43:43

Matthias Noback has a recent post to his site sharing some advice and examples of how to use Sculpin for your project's documentation to make it a quick and pretty painless process.

One of the key ideas is to generate documentation instead of writing it. This should help prevent duplication and outdated information that is not trust-worthy and would therefore be neglected. I'm currently looking for ways to technically accomplish such a thing with PHP projects. This should result in reusable tools which will make it easier and more fun to document future projects while writing the code.

[...] I wanted to use Sculpin to document another project, the main project. So I started figuring out how to run Sculpin and generate a static subsite (not a blog) based on files in a subdirectory of another project. It wasn't all that hard, but I'll share the steps here anyway.

He walks you through the creation of a new Sculpin-based site and how to test and ensure it's all working correctly with simple content, a layout and configuration. He finishes out the post mentioning the themes available for Scuplin applications and links to the Bootstrap 3 theme as an example.

tagged: project documentation sculpin static generator tutorial introduction

Link: http://php-and-symfony.matthiasnoback.nl/2016/12/project-documentation-with-sculpin/

Symfony Blog:
Introducing the new Symfony Documentation
Jul 29, 2016 @ 13:47:59

On the Symfony blog there's a new post introducing the new project documentation, the result of lots of work from a large number of developers to bring the framework's documentation up to date.

When the Symfony documentation was started more than 5 years ago, it was just a few short articles written by Fabien. Now, we boast more than 1,000 pages of documentation, a team of 4 maintainers and over 1,000 contributors!

As the project grew, we've tried to innovate: adding continuous integration to catch build errors, setup Platform.sh to auto-deploy every pull request and implemented a process so that all new features to Symfony's core become documented (an amazingly rare feat).

And just like with code, a project must challenge itself continuously to stay ahead of the curve. In this article, we're thrilled to introduce the new Symfony Documentation: a result of over 150 hours of volunteer work via a secret project codenamed "Project Mercury".

They talk about some of the challenges they faced with the previous version of the documentation and some of the problems they wanted to solve. Instead of splitting things up into three sections ("Book", "Cookbook" and "Components") they opted to break it up into something more approachable for two different categories of users: "Getting Started" and "Guides" (everything else). They share some about how they made this new version happen and the workflow they followed to keep everything (and everyone) in sync.

You can check out this new documentation over on the completely revamped documentation site right now.

tagged: symfony documentation project version release update

Link: http://symfony.com/blog/introducing-the-new-symfony-documentation

Symfony Blog:
Announcing the Fourth Symfony Docs Hack Day
May 13, 2016 @ 09:58:29

On the Symfony Blog they've posted the official announcement of their Fourth Symfony Docs Hack Day happening on May 21st. This hack day is focused on just improving the documentation for the framework, not handling bugs in the main codebase itself.

The Symfony project is proud to announce its fourth Symfony Docs Hack Day. This Hack Day will be an online event to give a push to the Symfony Docs before the Symfony 3.1 release at the end of this month.

[...] Hosts Ryan Weaver, Wouter de Jong and Christian Flothmann along with you and all your friends from the Symfony community. The Hack Day is for everyone - we need Symfony experts and newcomers. If you're new to Symfony, you give us a fresh look at the documentation!

The post gives you a bit of an idea what the event will be like and what you can expect, especially as a first time submitter. It will be happening completely online via the "#symfony-docs" channel on the Freenode IRC network. You can prepare by following some of the links in the post to pending pull requests and a list of missing documentation contents.

tagged: symfony hackday documentation update event irc freenode framework

Link: http://symfony.com/blog/announcing-the-fourth-symfony-docs-hack-day

Symfony Blog:
The New Symfony Documentation Search Engine
Apr 29, 2016 @ 10:49:27

In an effort to improve their "developer experience" (DX) around using the Symfony framework the development team has introduced new searching functionality to help more effectively find what you're looking for in the expansive Symfony documentation.

Symfony boasts one of the largest documentation pools ever written for an Open- Source project. Considering the ten different Symfony versions (from 2.0 to master) and including the code samples, Symfony Documentation has around 3.6 million words, more than three times the word count of the entire Harry Potter series.

They share some of the things they learned around creating a search engine ("it's hard") and what they ultimately ended up using - the Algolia service. The post talks about how they indexed the current documentation and broke it up into "chunks" of meaningful content. They also include the simple Javascript they use that links the search field to the Algolia service and renders the results using a view partial.

The proof of concept for the new search engine was a success and we decided to stop the ElasticSearch integration and stick with Algolia. The new search engine is greatly faster than the previous one and the search results are more accurate and relevant.
tagged: symfony documentation search engine new algolia service

Link: http://symfony.com/blog/the-new-symfony-documentation-search-engine

HHVM Blog:
Improved User Documentation
Dec 15, 2015 @ 09:05:32

The HHVM blog has a post today announcing some updates they've made around the documentation for the project and the release of the "next generation" of their documentation at http://docs.hhvm.com/.

Back in August, we announced that we are going full force in revamping user documentation. We sent out a public survey to gauge the standing on the existing documentation at the time. We had 160 responses to the survey. Those results served as both validation and a guide to our approach with the new documentation.

The survey showed some interesting results including that the existing documentation could use improvement, better content in certain sections and poor examples in some places. In order to help this they worked hard to revamp the documentation and created a new GitHub repository for the docs and allows developers to pull it down locally and contribute back content/corrections as they might catch them. They also lay out the new documentation structure, breaking it up into Hack, API and HHVM sections. Finally, they talk about the technology behind the site including the runnable code examples, how they're generated and what the build process looks like.

tagged: improved documentation user hhvm hack facebook api survey results

Link: http://hhvm.com/blog/10925/improved-user-documentation

Zend Framework Blog:
Zend Framework 3 Update and Roadmap
Nov 26, 2015 @ 09:47:33

On the Zend Framework blog they've posted the roadmap and latest updates on the work being done for the next major version of the framework: Zend Framework 3.

In October, while at ZendCon, I presented a talk on Zend Framework 3 entitled "Components, PSR-7, and Middleware: Zend Framework 3." You can view it online, but this post discusses current status, details some decisions, and points to the work still to be done. It's a long read; grab a warm beverage, maybe some popcorn, and take your time.

They start by outlining some of the major concepts that ZF3 integrates and are key to how it will handle requests:

  • the component-based system it's built on, making major use of Composer-style packages and installation techniques
  • using the PSR-7 standard for handling of HTTP requests and responses
  • the use of middleware to modify the request/response and add logic

Finally, they get into the overall view and roadmap for the framework. They talk about the ServiceManager/EventManager, the role middleware plays in the request dispatching and the goal of reducing dependencies. The post ends with a look at the improvements they're striving for with new and better documentation and the next steps in the roadmap for the coming months.

tagged: zendframework3 roadmap update overview psr7 middleware component documentation

Link: http://framework.zend.com/blog/zend-framework-3-update-and-roadmap.html

Symfony Blog:
How we Auto-Deploy Documentation Pull Requests with Platform.sh
Sep 10, 2015 @ 12:42:38

On the Symfony blog Ryan Weaver shares a "behind the scenes" look at how the project handles and has automated their documentation generation process with the help of the Platform.sh service.

[Symfony's documentation](https://github.com/symfony/symfony-docs) is an open source project with more than 800 contributors. That’s great! But our goal is to always make it easier to contribute and faster to merge in changes. And today, we’ve started doing something really cool to improve our workflow: integration with [Platform.sh](https://platform.sh).

Platform.sh is a hosting solution that provides out-of-the-box continuous deployment for Symfony, Drupal and any other PHP applications. It extends the concept of a Git branch at the infrastructure level. Basically, this means that it’s easy to deploy every branch and/or Pull Request to its own URL.

He talks about the documentation's format (Sphinx) and how, while it does provide flexibility it also can lead to maintenance issues too. Changes can't be seen immediately and it's difficult to review. Instead they worked up a process where each pull request was automatically deployed to its own unique URL. This reduces both issues they were setting around instant feedback and review problems and provides a better experience for the developer overall.

tagged: integration platformsh documentation request pull symfony continuous deployment

Link: http://symfony.com/blog/how-we-auto-deploy-documentation-pull-requests-with-platform-sh

SitePoint PHP Blog:
Fast Multi-language Docs with SitePoint’s RTDSphinx-PHP
Sep 09, 2015 @ 12:42:50

The SitePoint PHP blog has a tutorial posted showing you how to create multi-language documentation with ReadTheDocs and Sphinx with the help of the RTDSphinx-PHP library.

This post will guide you through getting up and running with RTDSphinx-PHP, a ReadTheDocs-friendly Sphinx based PHP documentation skeleton with sane defaults, pre-installed directives, and modified styles for optimal API and prose documentation rendering in multiple languages. For an unfinished example of the documentation, see here and switch the language in the bottom left flyout panel.

If this sounds familiar, it’s because we already went through a manual setup of a similar skeleton in a previous post, but that one had no localization support, too many steps, and wasn’t as reusable as this newly developed one.

He starts with the "quickstart" instructions to help you get the necessary tools installed to create the documentation. From there he gets into some of the main features the library provides including localization, a few utility scripts and syntax highlighting. Each of these comes with a bit of code/markup showing how to put them to use. The post ends with the instructions you'll need to push the documentation you've created up to ReadTheDocs and what the results should look like.

tagged: documentation multilanguage language readthedocs sphinx library

Link: http://www.sitepoint.com/fast-multi-language-docs-with-sitepoints-rtdsphinx-php/

SitePoint PHP Blog:
Using Sphinx for PHP Project Documentation
Aug 17, 2015 @ 09:19:04

The SitePoint PHP blog has posted a guide to using Sphinx, a documentation generation tool that's used behind the scenes for the ReadTheDocs hosted documentation service.

I recently had the need to write proper prose-like source-code documentation for the Diffbot PHP client. Having looked at several documentation generators, and even having suggested a @prose tag for importing of related MD/reST documents into method and class descriptions, I realized there simply is no perfect solution we can all agree on (yet). So until I extend Sage with a @prose token and reST parsing, I opted for ReadTheDocs and Sphinx.

He starts with a quick "TL;DR" of the necessary commands to get things working quickly but follows it with the full details. He walks you through the installation of Sphinx locally, setting up the folders and adding a custom theme. He show how to create the table of contents, activate the PHP syntax highlighting and how to show/hide the "Edit on GitHub" links. He also includes the steps to convert Markdown documents into the reST format and, finally, adding the project to the ReadTheDocs site and pushing your results.

tagged: sphinx project documentation tutorial readthedocs markdown rest

Link: http://www.sitepoint.com/using-sphinx-for-php-project-documentation/

PHP Roundtable:
026: Documentation & Developer Experience
Aug 05, 2015 @ 08:44:24

The PHP Roundtable podcast, hosted by PHP community member Sammy K Powers, has posted their latest episode - episode #26: Documentation & Developer Experience. Sammy is joined by guests Ryan Weaver, Taylor Otwell and Frank de Jonge.

Documentation can make or break a project but it's often completely overlooked until the very end. And if we don't think about how developers will interact with our project before writing our opening We'll discuss some strategies we can take to improve the overall developer experience with "good" documentation and clean API's

You can catch this latest episode either through the embedded video player on the PHP Roundtable site or directly on YouTube. If you enjoy the episode, be sure to subscribe to their feed and follow them on Twitter for notifications when the live recordings are happening.

tagged: phproundtable podcast video ep26 documentation developer experience

Link: https://www.phproundtable.com/episode/documentation-and-developer-experience