Developer Documentation

[kongondo]

@Teppo, about ApiGen...

I for one totally love it....but not the ProcessWire hosted one. I have rolled out my own locally hosted one, which I update regularly with the latest PW dev. It has been especially invaluable to me as a module developer and also as someone curious to find out how PW works and also just for  learning to use PEAR . I can quickly and systematically go through PW cross-referenced code, reading Ryan's comments, finding out what extends what, inherited properties/methods, class properties and methods, etc. I have set it up to document not only .php files but also .module ones - so, the whole package. GitHub doesn't even come close IMHO - unless am missing something?.

As stated previously elsewhere, my greatest influence as a developer has been through studying existing modules, notably by Ryan, Soma, Wanze, Pete, Antti and yours, and more recently others including Adrian. ApiGen has helped me 'decipher' Ryan's and Soma's advanced use of PW methods - quickly and efficiently (but I also use Grep a lot if I am looking for something specific). But I agree - this is something I would only recommend for advanced developers and has to be used with the full knowledge about 'Public vs Private API' as stated in the link to Ryan's comments...

I would just suggest that people use our regular API docs (especially the cheatsheet) and then use something like this apigen documentation for zeroing in on more detail about a specific function or class, if they need it. I think the apigen documentation could really be useful for contextual links to more detailed function reference, where applicable (like in links from the cheatsheet).

This has been written in a hurry so there could be mistakes

Edited March 17, 2015 by kongondo

[teppo]

GitHub doesn't even come close IMHO - unless am missing something?.

The things you mentioned are exactly what I use GitHub (and local PW installations) for, on a daily basis, though I can definitely see how ApiGen might work as a nice shortcut for some of it. Seeing inherited methods/properties is nice for an example, as it does often require opening multiple files to get the same stuff out of raw code.

Either way, I guess we can safely say at this point that it's a question of preference and workflow, and it's good to hear that there really are people who prefer this approach. Right now I think it's just a question of "how do we set up one that actually works"

I tend to work (again on a daily basis) with versions ranging from 2.1 to latest dev, so documentation based on the latest dev (or master) alone wouldn't be of much help to me. Hence my suggestion that one should be able to browse through all versions. Perhaps that's a rare need, though -- I don't really know? This is definitely one of the few things I like about the Zend Framework programmers reference; you can easily jump between versions.

@Kongondo, did you make any changes to your locally hosted version, or is it "just" an up-to-date off-the-shelf ApiGen? Is there something that we could, perhaps, benefit from? I meant what I said back there: even if I don't personally have much use for this, it would be kind of fun project to set it up so that it gets automatically generated either each time Ryan pushes something to GitHub (perhaps via webhooks), on a daily basis, or something like that

[Pierre-Luc]

@teppo, providing version information (matched against PW versions) is one of my goals, among others. This is both for Cheatsheet and Docs. Ideally we'd have @since tags in phpdocs for classes/methods, but right now they ain't there.. so it might require some work to figure this part out. For those who aren't familiar with them, here's an example :

 /**
  * Example of @since usage.
  *
  * @since 2.5.20 Added the $b argument.
  * @since 2.5.8 Added the $a argument.
  * @since 2.4.0
  */

I personally don't aim at using ApiGen, it's there but it's a totally different tool, though of course that's up for discussion as it's still useful but for different use cases. I wish we find a way to work on docs together, and decide how to organize things as a team. 

That said, I think right now our goal should be to arrange the docs in a more readable fashion, update the parts that haven't been updated and setup a good structure for docs content (this includes having info on which version the docs are for). My main inspiration is Symfony's documentation, it's just stellar; very clear with lots of code examples for common things. What Ryan has achieved so far is a very good starting point, let's improve on this.

I tend to work (again on a daily basis) with versions ranging from 2.1 to latest dev, so documentation based on the latest dev (or master) alone wouldn't be of much help to me. Hence my suggestion that one should be able to browse through all versions. Perhaps that's a rare need, though -- I don't really know?

Definitely not!

[teppo]

Ideally we'd have @since tags in phpdocs for classes/methods, but right now they ain't there.. so it might require some work to figure this part out.

I don't think I've ever seen or (knowingly) used that tag. Good to know that it exists, would definitely make things easier

[kongondo]

@Kongondo, did you make any changes to your locally hosted version, or is it "just" an up-to-date off-the-shelf ApiGen? Is there something that we could, perhaps, benefit from? I meant what I said back there: even if I don't personally have much use for this, it would be kind of fun project to set it up so that it gets automatically generated either each time Ryan pushes something to GitHub (perhaps via webhooks), on a daily basis, or something like that

Been planning to automate the process....either within or outside PW...e.g: 

https://github.com/apigen/apigen

https://github.com/ApiGen/ApiGen/wiki/Generate-API-to-Github-pages-via-Travis

[Pierre-Luc]

I don't think I've ever seen or (knowingly) used that tag. Good to know that it exists, would definitely make things easier

I didn't know about them either until a few weeks ago, I discovered that while thinking about documenting PW.  

I've also asked Ryan on GitHub https://github.com/ryancramerdesign/ProcessWire/issues/1015 to start using them. That would really help us out.

[Pierre-Luc]

Ryan accepted.

[Pierre-Luc]

So, anyone else up for the challenge? 

[qtguru]

Yeap so what's the next step ?

[Pierre-Luc]

I'd say, first let's set common goals; what do we want to achieve at the end of this. Then after that make a roadmap of what order we should tackle things, define how we share the work that needs being done. 

I would really like more input on what people want to see in the docs, we can probably use the forum and search for the most popular discussions for that, but there are limitations to this. Some topics have barely been discussed so it's hard to say apart from personal experience.

[qtguru]

Oh trust me i have a detailed list of things that should be in a tutorial can you give me this week to collate them. Week days are hectic for me. 

[Pierre-Luc]

Sure thing, it's pretty much the same for me.

[SteveB]

Just caught up on this thread. I think you are all several steps ahead of me on this but I'd like to help. Documentation matters. I like what's been said about automated docs and streamlining that process (apigen, webhooks, etc.). I like that people are recognizing how useful different types of docs are..

Some observations: JQuery docs site is pretty good as a quick reference for syntax, methods, etc. and has good simple examples nearby. The PHP docs have always been a pretty good function reference (and there are so many!). How they handle comments is interesting. There are good and bad comments but it's great having them, especially for quirky version specific and environment specific stuff. Over they years they've tried various ways to organize and filter that content. Currently they have up/down voting but that has the effect of pulling posts responding to earlier posts out of their context, making them somewhat ambiguous.

I'm particularly keen on using a PW web site to tie things together (eating our own dogfood). I'm just spewing coffee fueled ideas here, don't be too harsh, but somehow we should be able to use automatically managed tags, categories, etc to facilitate jumping around between tracing through code in apigen, seeing relevant "recipes", locating relevant posts (some curating and crowd sourced up/down voting here), Github issues and updates, etc. I'm imagining some kind of all-knowing sidebar navigation generated by PW and with AJAX, RSS and minimal intrusion could be be tacked on to things like the cheat sheet, apigen, this forum, etc.

[pwFoo]

Would be great to have some more up to date documentation. Apigen and cheatsheet seems to be outdated?

[GuruMeditation]

I hope this goes ahead. Together with the snippets site it would make PW so much easier to use.

I've been attempting to write my own full module lately for a site I'm working on, and it's not been easy in terms of finding certain examples to look at. It's been a case of looking through existing modules and searching the forum which can take up a lot of time. We definitely need documentation to aid us with creating our own modules, i.e module config options, tips for installing, upgrading and uninstalling our modules etc. It took me a while of trial and error to add a simple pre-checked checkbox to my module configuration page using the following code.

<?php

class TestConfig extends ModuleConfig {
  public function __construct() {
    $this->add(array(
      array(
        'name' => 'Enabled',
        'label' => 'If unchecked, module will be temporarily disabled throughout the site.',
        'type' => 'checkbox',  
        'autocheck' => 1, // => Autoset the default value
        'uncheckedValue' => 0,
        'checkedValue' => 1,
      )
    ));
  }
}

Examples of all other fields we can add to our configuration page would also be nice additions to the documentation.

Well that's just my thoughts, not sure if they are of any use or not.

[Pierre-Luc]

It's still something I want to get going, but recently I've had pretty much no time for myself. Between moving, the job and other things, I'm pretty late on most things.

More pairs of hand would definitely be a plus.

[Peter Falkenberg Brown]

Hi All,

Back in 2013, I spent a great deal of time sort of getting up to speed with v2.3.0, and built three major web database applications with that version (as well as some magazine style websites). Soma's CheatSheet was invaluable, as were the doc pages and the forums.

I stayed with v2.3.0 for a variety of reasons, for far too long, but now I'm digging in again to ramp up with the newest versions.

I've read through some of the discussions about the difficulty of spending the time to document things, (we all know that reality ), so I'm wondering if the ideas below might be useful, in the interim. I hope I haven't missed forum posts where someone already covered this.

* It seems to me that we have a significant amount of documentation already, but it's hard to dig through. Sources I see are:

1. The GitHub technical notes on each new feature, function, etc. Looks like versions newer than 2.3.0 started around page 22:

     - https://github.com/ryancramerdesign/ProcessWire/commits/dev?page=22

     - Can all of these tech notes be exported into a more readable format? For example:

          . a huge Word doc, or better yet:

          . a series of browsable, searchable PW pages, where each page is tagged with the PW version and the function names covered in the note

2. Ryan's blog pages and Teppo's Newsletter pages:

     - http://processwire.com/blog/page3

     - http://weekly.pw/issue/1/

     (looks like PW was at 2.4 at the beginning pages of both the blog and the weekly, so there's a bit of a gap

     - Perhaps the blog and and weekly pages could be tagged with the same values: the PW version and the function names covered,

          so that the GitHub List could contain links to those pages.

Essentially, I'm suggesting that we start with a list of new features and functions, etc, tagged by version, that would serve as an index of what's new since 2.3.0, which I believe is the version that the Cheat Sheet covered (not sure about that).

Then, if someone has the latest version, one could assume that all the functions in the list are relevant, and it's simply a process of then browsing through the index list and clicking over to blog/news pages for more info, or searching the forums for more info.

=> The main point, as I see it, is that an index like this would give us the list of what's new, as the starting point.

Without that, we don't even know what to look for, in terms of new features, functions, etc.

I would think that the very first step would be the export of the GitHub tech notes, into a PW set of pages,

followed perhaps by a simplified outline / index / table of contents list of all the major new functions and features.

Any thoughts?

Thanks to all!

Peter

[Beluga]

How do you guys like https://readthedocs.org/ ?

Real world example: http://bugzilla.readthedocs.org/en/latest/

[Peter Falkenberg Brown]

Dear Beluga,

Looks like a good app.... but then again, we have PW!

I think that someone could set up a cron job to look for new GitHub, blog, or news posts, and feed that data

right into the "PW Function List" application, so that it would always be up to date.

Just a thought...

Peter

[rick]

I do think this is a great project, and there are many great ideas submitted by everyone.

Based on my 'past-life' experience as a tech-writer, there are two approaches to this issue. One is from the target audience point of view, the other is from the product capability point of view. Since there are numerous entries in this topic where "I do it this way..." and "I do it that way...", let's set aside the point of view of the end user, and concentrate on the functionality.

To do that, each entry should have at least the following things defined:

• The description of what the function does,
• The proper syntax for its use,
• The parameters defined,
• The return values defined,
• A simple example of each combination,
• And a link to the source code.

I hate to admit it, but I really like the completeness of wordpress docs... https://codex.wordpress.org/Function_Reference/add_action It makes is very easy for any skill level to quickly obtain the necessary information to move forward.

I also think it would be advantageous to use ProcessWire to present this information. Eating our own dogfood, kind of thing.

I would like to participate on this team too, if I may.

[pwFoo]

Is there a way to generate up to date documentation (apigen, API, cheatsheat, captain hook) for stable and dev branch? Any plans for PW 3.0?

I told a friend about PW and he liked the PW API and possibilities, but he moved away because of the documentation. 

[Pierre-Luc]

It can be possible, but right now it's not ready to do that.

[SteveB]

each entry should have at least the following things defined:

• The description of what the function does,
• The proper syntax for its use,
• The parameters defined,
• The return values defined,
• A simple example of each combination,
• And a link to the source code.

To that I would add...

Links to relevant blog post or forum topic

A brainy search engine like Elastic Search

Comments from the community, snippets etc. with up/down voting (sort of like PHP docs)

It should be built on Processwire! That way the community can more easily contribute to getting it done and it becomes a great demo.

[Soma]

I've created the cheatsheet and there's a extended view of it. The idea is, that there would be more extended description and examples along with deprecated, introduced version etc. It's a work in progress and it's slowly going forward. This was built already 2 years ago.

I just fixed a bug that wouldn't show it to the public and many API entries are not yet worked on.

Cheatsheet and Extended docu is built on PW! We are a small team that has access to the cheatsheet PW backend. But practically anything would be possible to make this even more a place where dedicated people would be able to contribute. We're just not yet sure how. 

A good example would be http://cheatsheet.processwire.com/files/image-properties-in-addition-to-those-in-file/image-width/

[SteveB]

There is a lot of good info but all from different points in history. Figuring out what's true today usually means extra reading (not a bad thing, but time consuming). Fortunately the code itself is well commented.

When I look at the cheatsheet I'm always wondering if the info is current or a couple years old. Object properties like image->width (Soma's example) don't change much but other things do. New features turn up every week.

If documentations like this had a PW version number on each content item (the version the author was writing about, or has later verified is consistent with the article) we'd know better what else to look at.