Developer Documentation

[qtguru]

Hi usually I don't create topics until i feel they are necessary but this is really become a chore for me in development phase, The issue is the Developer Documentation; its really hard for me to get the necessary information I need. I have to go through various topics and navigate through conversations just to find what am looking for.

Just today I was looking for the API for the PageField to save a page as a value and I have no luck, I feel this can increase development time to those new to Processwire. i found out there's a site called wiki.processwire.com but it's been last updated 2012 and the cheatsheet.processwire.com doesn't go indepth enough for me to understand what's going on. 

ADVICE:

I feel we can have a documentation page where users can edit and contribute text to it gradually, there's recipe.processwire.com but its still not enough, it would cool to have something like this http://framework.zend.com/manual/current/en/index.html

Forgive my rant I come from a country where electricity is not guaranteed so its a big deal for me when I have to spend alot of time looking for information. I don't mind contributing examples or if we can find ways to allow community update the wiki.processwire.com.

THANKS GUY 

Still looking for how to use code to save a PageFieldtype with another page

[Nico Knoll]

Moved to Wishlist

[Nico Knoll]

Well I think you're right about this. In my opinion the wiki should be removed and it's helpful articles should become Tutorials in the Tutorial section (I think Joss is already working on this somehow?).

I guess with 2.6 or 3.0 there will be a new complete documentation but at the moment Ryan is busy enough making ProcessWire more awesome every day

Maybe there should be some kind of documentation team. Just an idea.

[Nico Knoll]

Btw.: A good way to find help is (at least for more advanced users) to directly look into the core files: https://github.com/ryancramerdesign/ProcessWire/blob/master/wire/modules/Fieldtype/FieldtypePage.module

And I guess you can just do something like:

<?php
// the page containing the page field
$mainPage = $pages->get('1234');

$mainPage->pagefieldName = $pages->get('4321'); // assign another page

$mainPage->save();

?>

[qtguru]

Well I think you're right about this. In my opinion the wiki should be removed and it's helpful articles should become Tutorials in the Tutorial section (I think Joss is already working on this somehow?).

I guess with 2.6 or 3.0 there will be a new complete documentation but at the moment Ryan is busy enough making ProcessWire more awesome every day

Maybe there should be some kind of documentation team. Just an idea.

Exactly because I know how much Ryan is working on Processwire Core, is why I felt the documentation can be created by a team, I like the idea of a documentation team, if you got ways to execute this ideas please let me know so i can join, I can sacrifice some Skyrim time to do this.

[LostKobrakai]

I can relate to that. What bugs me often are the arbitrary jumps from http://processwire.com/docs/ to http://processwire.com/api/. The sidebar is so similar I don't think anyone even noticing these the first time. And in /api/ are so many hidden informations, which serve for a great baseline understanding of processwire, it's a pity they are so hidden.

About your FieldtypePage issue:

$pagefield = $page->related;
// Objects are passed as reference
// so this is the same as $page->related->add()
$pagefield->add( $pages->get("id=1234") ); 
$page->of(false);
$page->save();

[Nico Knoll]

@LostKobrakai: That bugs me to. But it has an "historical" reason: Some time ago API was an own point instead of Docs. Then Tuts and Dev Directory and the Blog, etc. came and we decided to make a link called "Docs" in the header. And API is same as before (otherwise the urls would have changed) and only got a link from the Docs sidebar instead of the header... But I think we're working on that

[LostKobrakai]

I've guessed for that reason, but it's still a bit cluncy and with all of those great redirecting modules out here, it shouldn't be a great issue. Even after some time of using ProcessWire I'm still using the api sites on a daily basis. Only with my recent dive into module developement for pw I switched more and more to just look at the code on github / locally. But until you've interalised the modularity and oop priciples I think it's impossible to find answers there.

[qtguru]

@LostKobrakai @Nico Thanks alot guys sometimes its hard following the source since some methods are magical so its hard to pinpoint but am getting there. thanks

[Soma]

The extended cheatsheet I setup quite a while ago would be perfect for those small examples for the API. Unfortunately the team refused to work on it since 1.5 year. Kinda sad as I spent many hours setting all up with workflow and such and each contributor has assigned a section.

Instead they prefer to respond in the forums 100 times the same. /rant over

[Nico Knoll]

@soma: You mean like http://cheatsheet.processwire.com/page/built-in-fields-reference/page-url/ ?

[Soma]

@Nico yep.

[Nico Knoll]

@soma: this looks pretty nice but I think the documentation should be part of the main site and the cheatsheet should link to the docs pages. Shouldn't it?

[Pete]

The extended cheatsheet I setup quite a while ago would be perfect for those small examples for the API. Unfortunately the team refused to work on it since 1.5 year. Kinda sad as I spent many hours setting all up with workflow and such and each contributor has assigned a section.

Instead they prefer to respond in the forums 100 times the same. /rant over

I gave you a "like" but you know what I mean - you are right.

I think there are a few things like that where a truly community-wide effort might help but your particular case is something more experienced members would be better helping with - although there are simpler parts too that others could chip in with.

In the case of the cheatsheet though soma, if you want to look over mine and ryan's pages that are awaiting review in the backend of the cheatsheet I would happily look over yours or we can split them somehow? There are 17 awaiting review and I don't think they would take too long to approve

[Nico Knoll]

@soma: I can do stuff too, but you have to tell me first what's the difference between those pages and the documentation pages

[Soma]

@soma: I can do stuff too, but you have to tell me first what's the difference between those pages and the documentation pages

Thanks Nico. I think we got all sections assigned to someone already but sure there's always enough to do. I'll have a look when I get to it.

A good question. The difference is that it's more of a reference with examples for each API method or property. The documentation pages are good to get understanding with examples and the cheatsheet is built from the content from there (just without examples). Idea is to extend it and provide more examples for stuff that isn't covered on the docu pages. See it as a more comprehensive and compact version like the php api pages with comments and cross references. 

Most important maybe is that we all can edit those and have some cool options that the docu pages don't have.

[apeisa]

Nico, feel free to help me with $file and $image parts...

[Nico Knoll]

Okay, I just need some kind of access

[Pierre-Luc]

I'm reviving this thread! This needs to gain traction!

I would really like to improve the docs, and I propose we start a documentation team.

I've already started a Google Spreadsheet (open for comments, PM me your Google account for modification access) with a tree of the current documentation with comments and improvements (see What's in and What's missing or needs improving tabs). Note that this is mostly made from memory and notes I have laying around. I haven't personally read 100% of the documentation (these days I just go straight to the source code), so I would appreciate your input/feedback/additions.

I suppose a spreadsheet might not be the best way to go at it, let me know how you'd like to organize things moving forward.

Cheers!

[Nico Knoll]

Looks nice. When i'm back in Germany i'm going to do some additions (or would like to make some )

[Yannick Albert]

Keep the API-Documentation in mind: http://processwire.com/apigen/

[teppo]

Keep the API-Documentation in mind: http://processwire.com/apigen/

Regarding this, Ryan did originally raise some points about the (intended) public API vs. features intended for internal use only, which this tool doesn't always distinguish properly. I'm going to agree with those points, and perhaps even take them one step further, by stating that in my opinion this is not useful at all, and should be deleted to avoid unnecessary confusion. Considering that it was last generated for ProcessWire 2.2, it would seem that I'm not entirely alone with that opinion either

If you need to know how specific object behaves or what methods it has, this provides very little (or none at all) benefit over looking it up from GitHub where you'll also see the code, changelog, etc.

[Pierre-Luc]

@teppo, I've seen this comment already, and I must somewhat disagree. Some of us do work this deep when working on modules for example and some parts of the architecture could use quick explaining, without entering into a full on object/method reference. I wouldn't say it's a priority at all right now though, other higher level things need documentation badly before this.. 

[teppo]

@Pierre-Luc: that's good to know, thanks! Perhaps it's that I've missed what this thing is all about, or just a question of workflow, but at the very least this thing should be properly kept up to date, preferably automatically. It should also allow switching between versions, while we're at it. Only thing worse than no documentation is unreliable documentation.

Anyway, even if we forget the public vs. private API argument for a moment, what's the real benefit this thing provides in comparison to, say, GitHub repository? Is it a presentational thing, i.e. a list of objects (and another of exceptions etc.) instead of files in directories, tables instead of DocBlocks, no code instead of full code, and so on?

If you could explain exactly what the extra value is that ApiGen provides, I would be happy to see if I could, perhaps, help with the "keeping it up to date" issue, so that it becomes actually reliable. Personally I'd prefer more people working directly with code instead of adding weird layers on top of it, but if there's demand for something like this, at least we should do it properly 

[qtguru]

http://www.codersgrid.com/2013/07/15/daux-io-documentation-generator-using-markdown/

This is something we should look at it uses markdown and it could leverage on Github meaning the snippets could be updated via Github just like processwire recipe, its highly depressing switching from looking at source code to scanning forums for answers. and if not some of the community can take it in our hands to create a separate site for documentation just like the processwire recipe. 

P.S it would be better if documentation were contributed by us, that way the Processwire Dev team can work on the updates of Processwire rather than being bothered about documentation.