Jump to content

Developer Documentation


qtguru

Recommended Posts

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

  • Like 3
Link to comment
Share on other sites

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.

  • Like 1
Link to comment
Share on other sites

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();

?>
  • Like 1
Link to comment
Share on other sites

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.

  • Like 3
Link to comment
Share on other sites

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();
  • Like 1
Link to comment
Share on other sites

@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 :)

Link to comment
Share on other sites

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.

Link to comment
Share on other sites

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

  • Like 2
Link to comment
Share on other sites

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 :)

  • Like 1
Link to comment
Share on other sites

@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.

  • Like 2
Link to comment
Share on other sites

  • 1 month later...

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!

  • Like 5
Link to comment
Share on other sites

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.

  • Like 1
Link to comment
Share on other sites

@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.. 

Link to comment
Share on other sites

@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 :)

Link to comment
Share on other sites

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.

Link to comment
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now
×
×
  • Create New...