Michelangelo van Dam has a new post to his site sharing some of his ideas about the importance of documentation and how it relates to the overall security posture of a project.

In my previous post I described 10 steps we should take to improve security of web applications. In this article I'm going to describe the purpose of documenting a project and what information should be included.

He starts off with some thoughts about the purpose of documentation, how it can't ever really be considered complete, and the importance of its structure. He offers a few suggestions about effective documentation structure and how it can be formatted to make it easier to grow over time without getting too unwieldy. He then comes back around to the security aspect of project documentation. This includes information about the servers the system is running on, the services that are running and details about which secrets are used (but not the secrets themselves!).

He finishes up the post covering various technologies that can be used to help automate your project and make sure that it is well structured and easy to keep in sync with your documentation.

On the Laravel News site there's a new post sharing a workflow developed by Bill Clark that makes searching the PHP documentation with the Alfred tool easier.

PHP Docs workflow for Alfred by Bill Clark is a workflow for searching the PHP documentation from Alfred directly. The PHP Docs workflow code builds on Till Krüss’ Laravel Docs Workflow for Alfred that we recently covered.

[...] You can search the PHP documentation by opening up Alfred and prefixing your search with “php” and then the search term.

They give an example of how to search the documentation and a screenshot of the resulting list. You can find out more and get this Alfred workflow for yourself over on the GitHub repository for the project.

For those out there that are new to using the Laravel framework and are a bit lost in trying to figure out its structure, Laravel News has just the article for you. In this new tutorial they give you an overview of the Laravel codebase and how you should structure your applications to keep everything organized.

Getting started in a new codebase can be very overwhelming, even more so if you are new to programming. So where do you start? Where are the places to look to learn the most about a codebase? Let’s take a look at few common areas for Laravel.

They start by talking about project documentation and how it can play a vital role in the on-boarding of developers new to the application. From there the post goes on to talk about the composer.json configuration, route configurations, service providers, tests and some additional tooling. For each item there's a paragraph or two explaining its place in a Laravel application and, in some cases, links to other resources for more information.

On the Laravel News site today they've posted about an effort that's been started to help create simple and community-driven man pages (documentation, manual pages) for command-line tools.

The TLDR pages (too long; didn’t read) is a command-line project that aims to simplify man pages with useful, terse examples of commands. This CLI tool gives me even less reason to memorize the tar and curl flags.

The way the TLDR command works after you’ve installed it is by passing it a command for which you’d like to learn practical uses without combing the full manual.

The article shows how to install this tldr package via npm and make it global on your system to be able to use it anywhere. There are also options for other languages if Node.js isn't your thing. You can find out more about the tool and what features it offers over on the project homepage. They also link to the repository if you'd like to contribute back to the documentation.

On the SitePoint PHP blog there's a new tutorial posted from editor Bruno Skvorc looking at PHPBot, a chatbot tool that might help you look up PHP documentation questions a bit more easily (and quickly).

I came across PHPBot the other day (not to be confused with Botman or Fondbot) – a “chatbot” which helps you look up PHP manual entries and generates example code for them.

If you follow me on Twitter, you know I don’t believe in chatbots being chatbots – as someone who’s built some for both commercial purposes and personal ones, and as someone who was around in the age of IRC auto-responding scripts, I see chatbots as a little more than a marketing fad designed to impress today’s Snapchat generation. However, every now and then one will appear that’s actually useful. Could this be the one? Let’s take a look.

He starts off with some of the basic concepts behind the bot and examples of some of the output from documentation requests. He goes on to talk about the actual usefulness of the bot and provides some instances where it is still lacking in functionality. He also looks at several other subjects including Knowledgebase and Bugs, Autocompletion / Suggestion and Copy / Paste Friendliness.

On the CloudWays blog there's a new tutorial posted showing you how to create project documentation with Sami, a tool that takes the DocBlock information already in your code and makes it into something more human-readable.

Developers regularly create large blocks of code that form parts of API’s and other mid to large level projects. While there is a (more or less) agreed upon convention for code writing, every developer has a personal comment and documentation writing standards. Some add small cryptic notes while others attach full-length Google Docs that document the method or class in painful details. This problem becomes very severe when the number of end users increases and there is a need for proper documentation of the project.

[...] DocBlocks are important because they are used by a well known Symfony document generator package called Sami. Very popular in PHP community, Sami also provides the ability to create custom twig templates and work with versioned documentation on GitHub. In this article, I will use Sami and a GitHub project Sync Mysql data with Elasticsearch to automatically generate documentation.

The tutorial then helps you get the Sami package installed via Composer and how to execute it to ensure it's working as expected. Next it points you to a project to clone to help with the MySQL-to-Elasticsearch interface. It then helps with the creation of a configuration file, the results of a build and some additional tips for customizing the configuration for your environment.

The TutsPlus site has posted the latest article in their "Programming with Yii" tutorial series, this time covering the generation of documentation for the API code that's been created to power the application.

Recently, I wrote about building REST APIs for your Yii application and expanded custom APIs for our startup series application, Meeting Planner.

In today's tutorial, I'll introduce you to Yii's apidoc extension, which automatically generates browsable documentation for your code. I'm going to use it to generate API documentation for Meeting Planner.

The tutorial starts off with helping you get the extension installed (via Composer) and links to a few examples of the end result. The tutorial then goes through how to add your own comments to your current files that will be output in the final result directly. This includes open text descriptions and other DocBlock information. It then shows how to generate the documentation, how to navigate the resulting HTML pages and some examples of what it will look like for the current code.

On the Symfony blog, there's an article posted by Ryan Weaver helping to explain the new service configuration changes that are included with version 3.3 of the framework.

In less than 2 weeks, Symfony 3.3 will be released. It comes with a lot of new stuff, but there is one feature that stands out: the new service configuration. I am very excited about these changes: they're designed to accelerate development, make Symfony easier to learn and encourage best-practices (e.g. injecting specific dependencies instead of using $container->get())... without sacrificing predictability and stability.

The post includes an example of what the new configuration file format will look like and briefly explains some of the changes. For those interested in a more in-depth look, they also link to this page in the Symfony documentation that goes through the changes step by step. It covers the autowiring by default, autoload of services, controllers being registered as services and more. If you're planning on making the move up to v3.3 when it's released (or sometime after) definitely check out this guide to make the transition easier.

On the Laravel News site there's a tutorial posted from Dmitry G. Ivanov giving you some helpful tips on building your first Laravel package.

Laravel is a powerful and modern framework. It has tons of different features, which make our work faster and easier. But you can’t push everything into the single box. At one time or another, we’ve all been in need of something not implemented in the framework out of the box.

[...] A package can be a solution. Write your code once and use it in any number of projects. Maybe you found a bug, or want to make some changes? Do it just once in your package code and then pull required changes in all of your projects. Sounds good?

The article then breaks down the information into a few different categories:

• The First Step (checking Packagist for something pre-existing)
• Development
• Testing
• Documentation
• Release

He ends the post by pointing out that there's several other things to consider when creating your package but they're a bit more in-depth than a short post like this could tackle.

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.