On PHPClasses.org today they've posted the latest episode of their "Lately in PHP" podcast series - Episode #35, "Better Documentation for PHP internals".

With the inclusion of Zend Optimizer+ extension in PHP 5.5, the need for better documentation of PHP internals became more evident, so PHP contributors can write extensions that take the most of the core PHP features. That is one of the topics discussed by Manuel Lemos and Ernani Joppert in the episode 35 of the Lately In PHP podcast. They also talked about having more optimized PHP opcodes, some interesting PHP feature proposals that got rejected, as well the article about the top version control systems used by PHP developers.

You can listen to this episode in a few different ways - either through the in-page player, by downloading the mp3 or by watching the video of the recorded Google Hangout session.

In a new post to her site Francesca Krihely starts looking at the developer experience - how developers relate to your service and product and what kinds of things you need to be doing to help engage them.

I had a great brainstorm a few weeks back with the members of the Developer Evangelists meetup on the topic of the User Journey, or as I'll call it now, the Developer Experience. The main problem we wanted to solve was how we convert new users into experts or awesoms users. In many ways, a Community Manager and/or Developer Evangelist is responsible for driving user adoption and making users successful, so this is a topic near and dear to all of our hearts. I walked away with three key things that help improve the developer experience: Great Product, Great Support and Empowerment.

This post talks about the first point - the "great product" - and notes that, if the product isn't useful and enjoyable to use, even developers won't bother with it. She also talks some about the need for quality documentation and how it can be seen as a sort of "marketing" to developers.

Work on making your product fit for an awesome developer experience. If you build it, they will come.

On the Zend Framework blog they're asking for your help with the project's documentation. They're looking to the users and community members around the framework to help them make the documentation more useful and stay up to date.

A piece of software is only as good as its documentation. The Zend Framework team and a dozen or so contributors are working hard to improve the Zend Framework 2 documentation, but we still want you to help us improve it even more. Any kind of help is welcome and greatly appreciated.

Most of what they're looking for is clarity - they want to ensure that what's in the manual makes sense (and is correct for the release it relates to). They're also looking for feedback on what helps you learn best - tutorials, user guides, API docs, etc. Issues and suggestions should be posted to the issue tracker in github. If you're not sure where to start, check out the contributors guide.

On the Symfony blog there's a post from Ryan Weaver about an upcoming event the project is hosting and how you can help - the Symfony Docs Hack Day (on March 30th).

The first commit to the Symfony documentation was over 3 years ago, and since then, we've grown to include a full book, lots of cookbook entries, and sections for most of the individual components. [...] But as we grow, we want to stay aggressive and continue to improve the quality of the docs. This means ensuring that code examples are accurate and pages are easy to understand, balancing the info you need with excess technical clutter. [...] And this is where we need your help! Whether you're a seasoned-Symfony veteran, a beginner, or even if you don't think your English is very good, we'd like you to join us on March 30th for our first ever Symfony Docs Hack Day.

The event is a virtual one - everyone will meet up on the Freenode IRC network in the #symfony-docs channel on March 30th from 9am through 5pm Central EU time. Everyone's invited, not just those who are experts in the framework. Documentation updates are a great way to learn more about a framework too! If you're interested in what kind of updates they're looking for, check out this list of open issues with the docs on Github.

Scott Mattocks has wrapped up his series about LUCID development with the final letter of the acronym - D is for Documentation.

Despite mankind's best efforts, writing code is still clearly an exercise for talking to computers. It has not evolved to the point where talking to a computer is as easy and natural as talking to other people. That's why documentation is so important. Programming languages are just a translation of a developer's intent into something a computer can execute.

He points out that even a little documentation can go a long way (even in presentations with code in the slides). It provides context and the intent of the code, not just details about what it's doing. He proposes a compliment practice to test-driven development (TDD) that turns the documentation process around - Documentation Driven Development. This is essentially writing up what the code does first, then writing tests to check it and only then writing the code to make it happen.

If you're interested in the rest of the articles in the series, check out the LUCID article on his site with links to each letter's article.

Matthew Weier O'Phinney has posted the third part of his series about making RESTful APIs with Zend Framework 2 (parts one and two). In this latest part of the series, he talks more about documenting the API and what commands can be executed.

In this post, I'll be covering documenting your API -- techniques you can use to indicate what HTTP operations are allowed, as well as convey the full documentation on what endpoints are available, what they accept, and what you can expect them to return. [...] hy Document? If you're asking this question, you've either never consumed software, or your software is perfect and self-documenting. I frankly don't believe either one.

He covers a few reasons why you should document your API and where he thinks it should live to be the most useful. He includes a few different ideas and two things he definitely thinks should exist for your API - the use of OPTIONS and end-user documentation. The first is a HTTP header (ZF2 code example included) that tells the API consumer what they can do with an endpoint. The second type is more useful for the human reader, giving them a better overall perspective on what the API can do - still served through the API but in a bit more understandable format.

Recently Lorna Mitchell asked the wide world of Twitter about some of their recommendations of things not to do when creating an API. In this new post to her site, she gathers together those responses including comments about documentation, consistency and response codes.

Recently I tweeted as a #linktuesday link the 10 Worst API Practices post from ProgrammableWeb. Today, in search of some concrete examples of APIs implementing unhelpful antipatterns, I sent out a tweet for help: "What's the most frustrating inconsistent/misleading bit of API you've seen? Looking for cautionary tales!" [...] In the raft of responses (and thankyou all, this was fabulous, helpful and entertaining in equal parts!), there were some definite patterns that I'd like to share with you, in no particular order.

Comments came in from all over and talked about things like:

• Response codes not matching the content (ex. 200 on an error)
• NullPointerExceptions
• Different endpoints for single vs collections
• Order-sensitive XML in requests
• Poor error handling
• Bad documentation
• Incorrect content type handling

So there you have it, the sins to avoid in your own APIs. If you've encountered any of these, please accept my condolences.

In a recent post to his site, Brandon Savage has a few helpful hints to keep in mind when you're refactoring your applications to make them easier to maintain (and possibly perform better) in the future.

The downtime [of this week] provides a perfect opportunity for the aspiring software developer to do the one thing they are always told there's no time to do: make the code better for better's sake. With few deadlines and plenty of free time, most developers can get a few hours of refactoring in to their code towards the end of the year. They can rearchitect sections that were implemented with haste in September; they can write tests for sections that were untested in April. Put another way, the "lost week" can be redeemed.

He has a few recommendations, each including their own brief summary:

• Test Everything First
• One Method, One Job (Also One Class, One Job)
• Don't Be Afraid Of More Objects And Classes
• Remove Dead, Unused, Unnecessary or Old Code
• Document Your Code

Check out the full post for the summaries and links to other useful resources.

On the Liip blog Thomas Botton points out that the French translation of the Symfony documentation is no online and available for public consumption! He was a part of the group that worked on the translation.

A year ago, I started to work with the Symfony documentation French translation team. At this time, I was actually not imagining that it would take so long to get all that work done.. In case you don't know, as of today, the Symfony documentation team already wrote more than 300 documents! Counting 1 to 4 hours to translate one doc plus the time to review it, you get an idea of the overall workload! But anyway, it's done: the Symfony documentation French translation is finally live on symfony.com!!!

He also mentions some of his reasoning for being a part of the team including it being a way to get more involved with Symfony (and open source) in general and the benefit it now provides to French-speakers wanting to get into the framework. You can find the documentation here.

On PHPMaster.com today there's a new tutorial showing you how to generate API documentation with the help of the ApiGen documentation tool and some commenting in your code.

If you're writing undocumented code, you should stop this very moment. I'm serious. Drop everything, save and quit, and focus on improving this essential part of your workflow. [...] ApiGen is a docblock parser like PhpDocumentor. PhpDocumentor has been around for much longer than ApiGen, but unfortunately its development is somewhat stunted and it lacks in terms of modern documentation and examples.

He shares an example class, fully commented to show off the right way to handle the DocBlocks and goes through each of the "@" types and explains what they're for. Also included are the instructions for getting ApiGen installed (via the PEAR installer) and a sample command to generate the docs from the source. You can find out more about ApiGen and some of its other options on it's main site.