Menu

Subscribe

documentation

User stories are documentation

While writing up the draft docs for Joyent’s Container Name Service I leaned heavily on the user stories and use-cases for the feature. It has me realizing that we should consider user stories to be the first draft of the user documentation.

Indeed, consider that well-written docs and user stories have similar qualities: a user, goal, and benefit, in clear language that’s accessible in small, focused chunks.

The CNS docs are now in our core documentation library, and I’m happy that we’ve updated the content management system to support deep linking to individual headings, like this one about adding CNS service tags when creating an instance with the triton CLI.

I’m thinking about this and writing now because Alexandra has joined the team and is adding short screencasts that do more to “show, don’t tell” how to use the features while providing additional context. See this screencast explaining usage with docker, assigning vanity names, and her overview of CNS’ function and purpose. She’s been digging in to the existing documentation, asking questions, and driving a lot of improvements. All that had me considering the source material and the relationship to user stories.

Lessons Learned: Why It’s Better Not To Use Parentheses When They’re Optional

There it is in the PHP manual for return():

Note: since return() is a language construct and not a function, the parentheses surrounding its arguments are not required. It is common to leave them out, and you actually should do so as PHP has less work to do in this case.

I knew the parentheses were optional, but I’ve been merrily using them all along. And I probably would have continued doing so until I saw the second note attached to the docs:

Note: You should never use parentheses around your return variable when returning by reference, as this will not work. You can only return variables by reference, not the result of a statement. If you use return ($a); then you’re not returning a variable, but the result of the expression ($a) (which is, of course, the value of $a).

Installing PHP APC On RHEL/CentOS

  1. Yum up some packages:
    ```

    yum install php-pear php-devel httpd-devel

              </td>
        </tr>
      </table>
    </div>

  2. Install APC using pear (the pear installer is smarter than the pecl installer):
  
    When the installer asks about APXS, say ‘no’. </p> <div class="wp_syntax">
      <table>
        <tr>
          <td class="code">
            ```
pear install pecl/apc

          </td>
    </tr>
  </table>
</div>
    1. Tell PHP to load APC:
      ```

      echo extension=apc.so > /etc/php.d/apc.ini

                </td>
        </tr>
      </table>
    </div>

  4. Restart Apache: <div class="wp_syntax">
      <table>
        <tr>
          <td class="code">
            ```
/sbin/service httpd graceful

            </td>
    </tr>
  </table>
</div>

      Installing memcached On CentOS/RHEL

      Using info from CentOS forums, Sunny Walia and Ryan Boren, here’s how I got memcached running on my Dotster VPS:

      Install libevent:

      ``` wget http://www.monkey.org/~provos/libevent-1.3e.tar.gz tar zxvf libevent-1.3e.tar.gz cd libevent-1.3e   ./configure make make install ```

      Install memcached

      ``` wget http://danga.com:80/memcached/dist/memcached-1.2.5.tar.gz tar zxvf memcached-1.2.5.tar.gz cd memcached-1.2.5   ./configure make make install ```

      We will start the server to use 30 megs of ram (-m 30), listen on ip 127.0.0.1 (-l 127.0.0.1) and run on port 11211 (-p 11211) as user ‘nobody’ (-u nobody):

      ``` memcached -u nobody -d -m 30 -l 127.0.0.1 -p 11211 ```

      Get an error?

      ``` memcached: error while loading shared libraries: libevent-1.3e.so.1: cannot open shared object file: No such file or directory ```

      Show it the path to the library:

      ``` LD_LIBRARY_PATH=/usr/local/lib export LD_LIBRARY_PATH ```

      JSON on RHEL & PHP 5.1.6

      Stuck with PHP 5.1.6 on RHEL or even CentOS (and a sysadmin who insists on using packages)? Need JSON? I did. The solution is easy:

      yum install php-devel<br /> pecl install json

      The pecl install failed when it hit an 8MB memory limit, and I was clueless about how to fix it until I learned that the pecl installer ignores the php.ini. Turns out the best solution is to use the pear installer (which does follow php.ini settings):

      pear install pecl/json

      More bsuite Hacking

      Update: bugfix release b2v6 available. Some conversations with Chow Kah Soon, who’s site is full of diversions from work , finally convinced encouraged me to solve some small problems that were giving him big trouble. Chow Kah Soon is in the lucky, but rare, position of having over 20,000 unique daily visitors to his site, […] » about 400 words

      Involvement, Inclusion, Collaboration

      <a href="http://worcester.typepad.com/pc4media" title="peter caputa">Peter Caputa</a> dropped a comment on <a href="http://jeffnolan.com/wp/2006/03/02/utr-zvents/" title="UTR - Zvents">Jeff Nolan</a>'s post about <a href="http://www.zvents.com/" title="Zvents - Main Page">Zvents</a>. The discussion was about how online event/calendar aggregators did business in a world where everything is rather thinly distributed. Part of the problem is answering how do you get people to contribute content -- post their events -- to a site that has little traffic, and how do you build traffic without content? The suggestion is that you have editorial staff scouring for content to build the database until reader contributions can catch up, and that's where Peter comes in, suggesting that content and traffic aren't where the value and excitement are: it's the opportunity to involve fans in the event planning and marketing process. » about 300 words

      Using XML In PHP5

      Everybody likes documentation. The Zend folks posted this overview and SimpleXML introduction The O’Reilly folks at ONLamp offered this guide to using SimpleXML. Of course, there’s always the SimpleXML docs at PHP.net.

      Two problems: I haven’t encountered CDATA in my XML yet, but I do hope to develop a better solution than offered here when I do. The other is that SimpleXML chokes on illegal characters, a unfortunately common occurrence in documents coming from III’s XML Server.

      Doing Relevance Ranked Full-Text Searches In MySQL

      I’m going out on a limb to say MySQL’s full-text indexing and searching features are underused. They appeared in MySQL 3.23.23 (most people are using 4.x, and 5 is in development), but it’s been news to most of the people I know.

      Here’s the deal, the MATCH() function can search a full-text index for a string of text (one or more words) and return relevance-ranked results. It’s at the core of the list of related links at the bottom of every post here.

      For that query, I put all the tag names into a single variable that might look like this:

      $keywords = “mysql database php select full-text search full-text searching docs documentation”

      Then I do a select that looks something like this:

      SELECT * FROM wp_posts WHERE MATCH(post_title,post_content) AGAINST(‘$keywords’);

      The docs give a lot more detail, including how to do boolean searches.

      PHP Developer Resources

      Somebody asked for some links to get started with PHP. Of course I lead them to the PHP.net official site, where the documentation is some of the best I’ve seen for any product.

      I also suggested PHPDeveloper.org and PHPFreaks.com, though the truth is I usually Google any questions I have that the official docs don’t answer. Still, I’ve found some good info at both of those.

      Finally, the PHP Cheat Sheet at ILoveJackDaniels.com is pretty nice to have around (cheat sheets mentioned previously).