Member Avatar for NardCake

Hello! Currently I am working on a PHP project on my own that is slowly growing, before I really get it out there I want to begin working on some documentation. It's just that I'm unsure on how documentation is usually created, best practices on writing it, and how it should be organized. Wasn't sure where this should be posted, but thanks for any suggestions!

  • 4 Contributors
  • 4 Replies
  • 264 Views
  • 1 Hour Discussion Span
  • Latest Post Latest Post by Member #120589

Dani AI

Generated

A practical, low-friction approach for a solo PHP project is to treat documentation as two complementary outputs: an API reference generated from in-code docblocks, and human-facing guides (README, quickstart, examples, troubleshooting). pointing to phpDoc is the right direction for source-code docs; and calling out alternatives is useful context when format or multi-language support matters.

A compact workflow that keeps docs useful and maintainable:

  • Keep a one-paragraph README and a one-minute Quick Start at the repo root.
  • Document every public class and method with phpDoc-style docblocks and generate an API site from those comments.
  • Add an examples/ folder with small, runnable snippets and a docs/ folder for longer guides.
    Automate generation and publishing in CI so docs always match released code. Minimal docblock example:
/**
 * Calculate total price including tax.
 *
 * @param float $subtotal
 * @param float $taxRate
 * @return float
 * @throws InvalidArgumentException
 */
function totalPrice($subtotal, $taxRate) {
    // implementation
}

User-facing docs are easiest to navigate when split into Quick start, Installation, Configuration, Usage examples, API Reference, Troubleshooting, Migration guide, and Changelog. Follow simple conventions for release notes and versioning (see Keep a Changelog and Semantic Versioning). Host generated HTML where it is searchable and stable (for example, a static site or GitHub Pages).

Operational tips: treat docs as code—store them in the repository, require PRs to update docs, lint and test example snippets, and run a CI job that regenerates and deploys the site. If installation of a generator feels confusing (as noted), prefer installing tools via Composer or running them from a container to avoid local dependency issues.

Recommended Answers

All 4 Replies

Member Avatar for pritaeas

For sourcecode documentation, PhpDoc is useful. User documentation is often written with help tools, if you want more than just a document (e.g. Help and Manual).

Edited by pritaeas
Member Avatar for Member #949455

Hello! Currently I am working on a PHP project on my own that is slowly growing, before I really get it out there I want to begin working on some documentation.

What mention pritaeas is a good choice. I was about to post it too.

You can read this and get an idea how to write it:

http://manual.phpdoc.org/HTMLSmartyConverter/HandS/li_phpDocumentor.html

After you write the documentation find a software to display the doc.

You can look at this:

(which is what pritaeas post)

I don't write docs this is the closes format I have used (you can look at this):

http://pear.php.net/manual/en/package.php.php-codesniffer.coding-standard-tutorial.php

It's kinda neat.

Edited by Member #949455 because: grammer
Member Avatar for NardCake

Okay thanks, I will take a look and try to figure out what's going on. Especially the link pritaeas gave, I'm still trying to figure out what it does and how to install it lol.

Be a part of the DaniWeb community

We're a friendly, industry-focused community of developers, IT pros, digital marketers, and technology enthusiasts meeting, networking, learning, and sharing knowledge.