News Feed
Sections




News Archive
feed this:

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

Symfony Blog:
Symfony 2014 Year in Review Symfony Documentation
December 31, 2014 @ 10:37:11

The Symfony blog has posted an update from the perspective of the documentation for the framework. Their "year in review" includes details for each section and the updates made.

2014 has been the busiest year in the entire history of the Symfony Documentation thanks to the amazing work of our documentation managers (Ryan Weaver, Christian Flothmann and Wouter De Jong) and the hundreds of documentation contributors.

They also talk about the best practices book, the new quick tour and Fabien Potencier's own How to Create Your Own Framework series. Among the list of their top ten most popular pages are the docs for:

Check out the full post for the rest of the list and what changes were made in each section.

0 comments voice your opinion now!
symfony framework documentation update yearinreview 2014

Link: http://symfony.com/blog/symfony-2014-year-in-review-symfony-documentation

Developer Drive:
Simplify your documentation process with Couscous
December 19, 2014 @ 12:14:49

On the Developer Drive site today there's a quick post introducing you to Couscous, a PHP-based documentation generation tool. Couscous translates your Markdown files into HTML output that's professional and clean looking.

If there's one thing I hate more than tracking down bugs, it's documenting code. It takes forever, it's almost a project in itself, and I never seem to factor it into my project lifecycle. Setting out to solve that problem for me, and anyone else whose life is too short, is Couscous. Couscous takes markdown files and converts them into professional standard HTML docs that colleagues, or fellow developers, can easily follow. You can preview the resulting site on your local machine, correct any issues, and then deploy straight to GitHub where it will be hosted for you.

They walk you through the (brief) process of getting the tool installed via Composer and using it to show you a preview of your documentation. The "deploy" command then allows you to easily deploy the results out to a GitHub Pages location on the gh-pages branch. You can find out more about Couscous on the project website.

0 comments voice your opinion now!
documentation couscous tool markdown generate html output

Link: http://www.developerdrive.com/2014/12/simplify-your-documentation-process-with-couscous/

SitePoint PHP Blog:
Writing API Documentation with Slate
December 15, 2014 @ 13:46:59

The SitePoint PHP blog has a new tutorial for the API developers out there showing you how you can use Slate for creating documentation. They point out a few other tools or formats you could use, but focus in on Slate, a Markdown-based tool that converts the result to HTML.

So you've built yourself an API. Perhaps it's RESTful, RESTlike or something else entirely. [...] There's one more thing, however. Thing is, an API is only as good as its documentation. That applies if it's for internal use only - perhaps it's for a JavaScript-based one-page app, or a mobile application - but even more so if it's for public consumption.

He includes an example of what the output looks like first so you know what the end result will be (and if it meets your needs). They then walk you through the installation of Slate and a few Ruby tools you'll need to generate the HTML output. He includes a simple example of the configuration and a simple document with four sections. He also shows how to use includes, alerts, tables and a sidebar. Finally he gives the "rake" command to build the documentation and how to you can push the result up to your own GitHub Pages.

0 comments voice your opinion now!
slate api documentation tutorial install configure example

Link: http://www.sitepoint.com/writing-api-documentation-slate/

Allan MacGregor:
Working with Psysh
April 14, 2014 @ 09:24:34

Allan MacGregor introduces you to Psych in his latest post today. Psysh is a runtime developer console, interactive debugger and REPL for PHP.

Psysh is actually more than a simple REPL it's also an interactive debugger; which means you can say goodbye to the endless barrage of var_dump() and die() statements. But do we really need another REPL for PHP, well honestly we could probably get by with the solutions currently available however Psysh has an extremely interesting Ace under the sleeve, it can also function as a realtime debugger.

He includes a few terminalcasts showing some of the commands Psysh offers from the expected output of variable value out to a handy link to the PHP documentation. An example of the useful object output is also included, enabling the showing of methods and properties.

0 comments voice your opinion now!
psysh repl debugger console documentation debugger

Link: http://coderoncode.com/2014/04/03/working-with-psysh.html

SitePoint PHP Blog:
Keeping Your PHP Code Well Documented
February 19, 2014 @ 10:15:19

The SitePoint PHP blog has a new post by Jacek Barecki talking about documenting your code and some suggestions for keeping this documentation useful.

Pretty much every PHP developer writes comments along with the actual code. But the language itself doesn't impose any rules on how to do so. You just have to wrap them around some specific tags and then you can write any content you want. So what exactly should be put in the comment blocks to keep them useful? Which parts of the code should be documented and which shouldn't? In this article I will present some important rules which may help you in keeping your PHP code well documented and understandable.

There's three suggestions included in the article, each with a bit of explanation and a few screenshots to illustrate:

  • Write code that explains itself
  • Keep the balance
  • Remember about the doc blocks
0 comments voice your opinion now!
documentation understandable useful tips tutorial

Link: http://www.sitepoint.com/keeping-php-code-well-documented/

SoftLayer Blog:
Four Rules for Better Code Documentation
September 24, 2013 @ 12:07:56

On the SoftLayer blog today there's a new post with some recommendations for better code documentation - four tips to help make things clearer and cleaner.

Last month, Jeremy shared some valuable information regarding technical debt on SLDN. In his post, he discussed how omitting pertinent information when you're developing for a project can cause more work to build up in the future. One of the most common areas developers overlook when it comes to technical debt is documentation. This oversight comes in two forms: A complete omission of any documentation and inadequate information when documentation does exist. Simply documenting the functionality of your code is a great start, but the best way to close the information gap and avoid technical debt that stems from documentation (or lack thereof) is to follow four simple rules.

Their four recommendations cover several aspects of documentation:

  • Know Your Audience
  • Be Consistent - Terminology
  • Forget What You Know About Your Code...But Only Temporarily
  • Peer Review

They've also provided some examples of what they're talking about with PHPDocumentor-formatted comments.

0 comments voice your opinion now!
code documentation rules suggestion phpdocumentor phpdoc

Link: http://blog.softlayer.com/2013/four-rules-for-better-code-documentation

Community News:
phpDocumentor2 Celebrates their (Stable) Version 2.0 Release
August 09, 2013 @ 12:04:35

As is mentioned in this new post to the project's releases, Mike van Riel and the contributors to the phpDocumentor2 project have released version 2.0 - the first stable release!

We have spent the past two months fixing bugs, adding tests and writing a brand new template. With this release it is now easier than ever to generate your documentation. And as a special party gift we bring you a brand new template, called Clean. Can't wait to see what it looks like? Then come over and see the demo.

He talks about some of the things yet to come for phpDocumentor including more features based on the PHPDoc standard, improving performance and making the existing systems (and templates) more robust and usable. You can find the full roadmap here. phpDocumentor is one of the most widely used PHP-based tools for generating automated documentation from docblocks already in your code.

0 comments voice your opinion now!
phpdocumentor documentation automated stable release

Link: https://github.com/phpDocumentor/phpDocumentor2/releases/tag/v2.0.0

PHPClasses.org:
Lately in PHP, Episode 35 - Better Documentation for PHP internals
May 09, 2013 @ 09:12:10

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.

0 comments voice your opinion now!
better documentation internals latelyinphp podcast phpclasses

Link: http://www.phpclasses.org/blog/post/207-Better-Documentation-for-PHP-internals--Lately-in-PHP-podcast-episode-35.html

Francesca Krihely:
On the Developer Experience
May 03, 2013 @ 09:22:07

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.
0 comments voice your opinion now!
developer experience product support empowerment documentation marketing

Link: http://francescak.me/blog/2013/05/02/on-the-developer-experience

Zend Framework Blog:
Help us improve the documentation!
March 29, 2013 @ 11:07:53

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.

0 comments voice your opinion now!
improve documentation help zendframwork github



Community Events





Don't see your event here?
Let us know!


configure series opinion laravel release community interview symfony threedevsandamaybe language framework list composer introduction voicesoftheelephpant podcast api unittest conference version

All content copyright, 2015 PHPDeveloper.org :: info@phpdeveloper.org - Powered by the Solar PHP Framework