Why is there no $page->isPublished() method?

[bfncs]

Hey Soma and Joss,

both of you are pretty right! As you may have noticed, I'm still pretty new here (coming from mostly MODX and CakePHP), so I hope you can understand that I'm eager to spread the word and convert more people to this beautiful system!

I think the wiki is the right place for this as it already has categories for Short and Long Tutorials. I'm definitely going to work on something to go there in the holiday season at the latest.

What do we do now about Page::isPublished()?

Edit:

If in doubt, go down the pub - worked for me for years till my liver pointed out a few rather obvious problems with the theory.

[Joss]

What do we do now about Page::isPublished()?

Put it in the Wiki?

In the longer term I think there will be a proper documentation system based on PW. But for the moment, the Wiki is an excellent collecting and collating system to start getting what is needed down on paper ,,, er, as it were.

Ryan is away for a few days I believe, but any that do not have a wiki account can ask him when he gets back.

Joss

[bfncs]

Put it in the Wiki?

Hmyeah, but where is the wiki section for desired new features? Or would it be better to post in the Whishlist & Roadmap subforum?

Ryan is away for a few days I believe, but any that do not have a wiki account can ask him when he gets back.

I was just asking because there was no feedback from Ryan so far, so probably it's ok to just wait.

I'll definitely ask for a wiki account when he's back, thanks a lot for pointing this out.

[Joss]

Hi Boundary

Perhaps I was being a little flippant ... sorry. It is my advertising background getting in the way again!

Yep, put it in the forum wishlist, assuming it is not already there - worth checking.

[bfncs]

Didn't see any flippancy there, no worries

On the contrary, I'm really appreciating how much work a lot of people put in the community here!

[Joss]

I'm really appreciating how much work a lot of people put in the community here!

So do I, which is why I am trying to give back.

I am not a programmer so I cant help with the development, but I am a writer, so I may as well give a bit of time to the docs.

Mind you, the lack of being a programmer may be a touch of a problem there as well, but at least I have people here to ask

(Which is more than I can say for some other application forums....)

[Pete]

I want a full-blown "Getting Started with ProcessWire" manual.

I don't think I'm thinking too far ahead either - take a look at the MODx manual for example: http://modx.com/learn/modx-books/modx-the-official-guide/ - anyone who's used MODx can see that by looking at the contents pages it covers each aspect of the system nicely.

I daresay that a similar approach with a PW manual would be easier to write since it's easy to use and explain - I also wasn't joking when I said somewhere else that Joss' overview of pages should be the first page anyone reads.

In terms of what documentation would be useful, I honestly think it would be sensible to think of it in terms of a book that takes you from complete beginner through to basic and intermediate examples.

Once you get into the advanced modules and scenarios you're often outside of the scope of normal documentation as you'll be talking about something very specific and that's where the forums help immensely. Perhaps with enough advanced tutorials there's scope for a second manual for advanced usage?

I'm all for the idea of a manual that's downloadable via PDF and that can also be bought online pre-printed. What do you guys think?

Sorry, going way off topic now

Should we at least think about a contents page to get the structure of what people think is useful to learn in one place? (Apologies if this is already on the WIKI - typing at speed on my phone).

[Joss]

Pete, you are spot on.

As a sound engineer and advertising producer/copywriter over the years, every product launch I was involved in never happened until the the user manual was completed - even if that was just how many spoons of the product you put into your tea cup! It was right up there on the top of the todo list.

Open source products have a huge problem with documentation.

The first is unsolvable: Any product that is basically one person working on the project more or less as a hobby (they have a full time job) and not having any proper way to finance it, simply is not in the position to write a full, properly crafted, user manual on top of the basic technical documentations.

As a one-person cottage industry they quite possibly don't have the skill-set either; Ryan has good communication skills, but that is rare. Just to compound the problem, there is a high chance that they don't speak the most useful language, English, as a native language. (To be honest, some of the stuff I have read over the years sounds like someone struggling with the language, only for me to discover that they ARE English!!!)

The second is a sort of bad habit .... the more users you get, and therefore the more experienced users you have, the larger the group gets that doesn't have a need for a proper user guide/book.

The trouble is that it is easy to forget that you have a growing number of users on the periphery that are simply struggling, that really could do with the help/education.

Even wonderful cross-referenced documentation (some people have listed some great examples that they have found) does not do it.

That comes into play once you have really got your head into the system and now need to know how to programme up those one thousand and one ideas you have just had.

So, I agree. A book.

And you could go the whole way here - a proper book.

There are several advantages:

1. Those that are involved in writing it can get a little bit of income from their hard work. (probably not very much!)
   
2. The project itself can get a small amount of finance from the publication.
   
3. It becomes a marketing tool that by being promoted, promotes the initial project.
   
4. By making the system incredibly accessible to a huge range of people with different skill levels, it broadens out the user base, which inevitably promotes the project again, with all the spin offs that can engender.
   

So, three sets of information.

1. Core Documentation

Definitely free - built on the API (or expanded from it), that gives basic examples in a small chunk fashion. Matthew Scheneker has started playing with an idea using PW for that, which could be interesting.

2. Basic Start tutorial

Free again - a walk through on the lines that I have been playing with on the Wiki that takes the user from nothing to a fully working site with a couple of tricky bits thrown in.

3. A complete book

Probably sold through something like Manning or Kindle, that not only takes the user on a journey using ProcessWire from just listing planets to creating full, complex applications, but also teaches them the basic PHP/PW knowledge they need to achieve that.

The only assumption it would make about the user is that they have some basic working CSS/HTML knowledge and are keen to learn using good working practices.

This sort of book does not need to alienate the more advanced user (very, very advanced users probably would not buy the book anyway), because it can be structured and laid out with sidebars and so on that can be skipped by those who "know how to do that."

As someone who would benefit from such a book, I would also be very interested in collaborating on it with someone who had all the necessary technical knowledge.... (hint)

Is ProcessWire ready for this?

If I look back over the last 15 years or so of playing with the internet I do seem to crop up in a rather large number of forums, beta testing lists, the odd article and so on .... Can be quite embarrassing (and thank goodness most of those have vanished along with the projects) .... . So maybe I have a little more industry experience than I sometimes admit too.... purely from the edges, you understand. (and it is true about having bugger all programming skills!)

So, I was reading a long forum post on the Symphony forums from 2011 by Ryan - http://getsymphony.com/discuss/thread/79645/ - which included a little bit of the History and gave me a little more insight into the product and it's creator than I got here.

My gut feeling is that PW as a concept and an application is well and truly ready for the big time. But some of the bits that surround it (official knowledge base, outside user knowledge, expansions) are not quite ready.

But all that means is that this it the time to do them, not that PW should wait for them.

I think a book should be written by a couple of idiots, that the community should get behind more docs and stretching the API out to its logical conclusion, that more people should be encouraged to create modules (with some good, strong QA behind the system), and that LOADS more profiles should be created or donated (or even sold!) that can show what it possible and can be used as learning structures.

There you go Pete - you asked the question, and that was my short little answer ....

Joss

[Joss]

Oh, missed the "Contents Page" bit.

So ....

• Forward (by Ryan - why he made PW, short history)
  
• Stepping Stones - How to cross the river using PW. Basically, how PW uses the relationships between pages and templates to allow you to find your own path and create solid applications and websites.
  
• Quick - do something before it gets boring! A bit like the Planets Tutorial, this is a short, silly one page site that proves the system is actually working.
  
• Overview of the learning process - How this book will work, what steps it will take you through, what experience you need (not much) and what you should get out of it.
  
• Creating the Tutorial Site - Effectively this is the tutorial I have just written on the Wiki, but more nicely laid out. It creates the basic starter site that the reader will use for all subsequent tutorials and explains some of the most commonly used techniques.
  

From that point on the book gets more and more complicated. Every technique is explained via a proper working example added on to the core Tutorial Site. The reason for doing this is that the writers CANNOT shortcut and suddenly assume that the reader can read their minds. It also means nothing is suddenly in isolation and is not properly explained.

These should not just be about creating things like galleries, forms and so on, but about how to manipulate data - a basic accounts system, a complex directory system, a forum built using ProcessWIre? If it is possible, we should demonstrate at least the basic building blocks.

The latter half of the book would have a lot of reference material (different coloured pages, in an ideal world):

• The Data Model - a full description of how the data structure works, why it is designed like that and how it can be used to meet high standards of data integrity and portablity. This should also include best practices for creating fields that that keep associations between types of data without over fragmenting. (For instance, if you have a field called article_body, it makes sense to use it for anything that could properly be called an article, but would not make sense to use it as a description field for a product listing)
  
• The API
  
• Snippets reference - this would possibly be repeats from within all the tutorial text, repackaged and represented as a reference (an electronic version would do some of this automatically, I suppose)
  
• Index ... and so on.
  

Another thought:

Is PW enterprise ready?

If so, that is an issue that should be looked at separately, since that sort of audience would need a different approach. Possibly not yet .... but maybe worth planning for.

Joss

[Pete]

I'd like to nominate myself as an idiot involved with the book

In what capacity I'm not sure, as I often fail to finish what I start in a timely manner when it's not generating income.

I have InDesign which I would see as essential to getting it into a publishable format for PDF and print, and I'm sure there must be a standard page size for both Europe and US (thinking ahead to getting copies printed on an as-needed basis using online publishers).

I think this has digressed enough to warrant its own topic. Perhaps simply a Documentation forum would be a good idea that's purely for discussing documentation and not getting mixed up with the Tutorials or Getting Started forums - just thinking there are a lot if discussions to be had around writing a book!

[Joss]

Er ... well you are the Admin! Go and create it!

[diogo]

Great step forward Joss. I don't think I can help a lot with the content, but I would love to take care of the design when it comes the time.

[Soma]

Joss, you forgot the excellent Cheatsheet! Invaluable tool and reference on one sheet, it was the first thing I did when starting working with PW. The API docs where too much spread out and inaccessible. It was great as there was no need to write long Texts, only copy paste it from the API documentation.

Also we shouldn't forget what newcomers and not so coders struggle with: Fieldtypes Images and Pages, and how they're handled. I.e. The single <-> multiple difference. This basic understanding has come up a gazillion times and everytime you find yourself explaining the same thing over and over. . The second most thing that comes up IS NOT PW related but, raw HTML JS and PHP things, that has nothing to do with PW at first.

I can't see much else where newbies struggle with except maybe with plain PHP and coding as general, which I think goes maybe to far to cover all this in a PW documentation. One thing is how to SETUP a field which is already covered inline in PW itself a good part! And the other using it in code and understand technical backgrounds and best practices in making front-end code. For me this is where it get's interesting, but has not much to do with PW at the end.

[Joss]

Arf'noon Soma

Oh, no, I haven't forgotten the cheat sheet - and that should make up part of any online system where it can be used as much as a cross referencing index as anything else.

And ....

Er. I think I said all the newbie stuff in my long post up there ↑

But yes - I think the Book is particularly well suited to taking people who have basically an html/css understanding (not expert, but can work through it) and then taking them bit by bit through the rest.

However, as I said a couple of posts ago, it needs to be laid out in such a way so if the actually know the technique, they can easily skip it without losing their place.

One of the big pit falls of many of the books out their (even the properly published and edited ones) is that if you miss a section because you know how to do a foreach loop, for instance, you suddenly find that within that bit there was also something important that you DIDN'T know.

So, getting that right is important.

By the way, I see nothing wrong with teaching good PHP practice using PW as the tutorial stage. Good marketing that!

Joss

[Pete]

I think the Cheatsheet should also be in the book. Not sure quite how to lay it out but I have seen other examples in other coding books so I'll have a look as there will be something sensible. Maybe we can have a pull-out poster (someone suggested a tea towel the other week which isn't a bad idea ).

A book can also be used well with downloadable examples - you could quite easily tell people to download the software, grab some example files that have the bare bones of a HTML template and get them to integrate a basic HTML template (separate from ProcessWire) into ProcessWire. Maybe the best example is to have a basic 5 page website currently built in HTML that has a basic contact form (doesn't need to work) and a basic gallery, and then integrate it with ProcessWire. My thinking here is that the majority of people who know how the basics of HTML and CSS will be used to working with a template of some sort and will want to integrate it with ProcessWire.

That's an idea anyway. It's certainly my starting point for any website - built the template in HTML and CSS and then integrate it with the CMS.

The start of the book needs to be thinking of the chapters and contents of each chapter and build it from there. Once that's decided upon you can fill in the pages - easy

I agree that linking to PHP.net pages is a good idea if we think there are areas that people should or would like to read up on more that they get linked to in the sidebar or whatever.

[diogo]

My personal preference is that the book is not dependent on example files. I prefer to study by books than on the screen, and also prefer to take them with me and read anywhere. I always get a bit irritated when the flow of the book depends on me sitting by a computer...

[Joss]

My personal preference is that the book is not dependent on example files. I prefer to study by books than on the screen, and also prefer to take them with me and read anywhere. I always get a bit irritated when the flow of the book depends on me sitting by a computer...

I agree with this. It is the same trouble that I have with Video tutorials - video is a great way of giving overviews and showing what is possible and even how easy something is, but it really does not replace the written word.

Having said that - being able to download things like a library of snippets used is rather nice - but that should be part of the online docs anyway.

Joss

[Joss]

That's an idea anyway. It's certainly my starting point for any website - built the template in HTML and CSS and then integrate it with the CMS.

The start of the book needs to be thinking of the chapters and contents of each chapter and build it from there. Once that's decided upon you can fill in the pages - easy

One of the most interesting things about ProcessWire for me is that you really can sit down and design an HTML site, then reverse it into ProcessWire. That is something that needs to be flagged up with all types of docs.

By the way, can you set up the forum?

How about:

Documentation Project

--- Book,

--- Online Documentation Project,

--- Wiki

--- Translations

That way, the broader community can stick ideas into the right holes!

In the nicest way, of course.

The last one I just thought of and is me thinking ahead a bit. At the moment this is predominantly an English Language project, but there are already users from all over the place; in the future, some may well want to take growing documentation and translate it. So, this might have use.

Joss

[Pete]

Not a bad idea. I am aware that there are already a lot of forums and maybe better ways of organising them so I've got a doodle I want ot run by ryan before adding too many more.

When I said coding examples for download, I just meant if someone wants to use the starting HTML-only template and integrate it rather than starting from scratch and typing every example in the book. Just thought it might be easier than having to type the HTML as well.

[Joss]

Oh, go on, punish them ... make them type it!!!

No, you are right, of course ....

[bfncs]

Just read through all of your discussion about better and more documentation/tutorials and I think that this is really great and I can't wait for all of this to start! Also, I hopefully get to volunteer in writing a tutorial or two, just to give back.

There's just one thing (aah, it had to come), that I'm not really fond of, and it's the "sell" thing. While I think it's perfectly ok to publish a book and earn money with it, I would favor if this effort would be put in some freely (in the sense of beer and thoughts) available product - especially if the works comes from the community itself. Not so much because of the money involved, but much more to get this out to everyone interested. I would also support the urge to get this out on dead trees, since this is something nice to have, but I'd really appreciate if there would be an open online version of it.

That being said, I really like the ideas about the book structure, this might be the right thing for a lot of beginners. Might be a good place to throw a link to the CakePHP Cookbook into the discussion, which greatly accomplishes the job of being readable from top to bottom and also serve as a highly interlinked reference.

Edit:

Oh, while this thread really drifted apart, I'm still interested in discussion of the nonexistent isPublished() method.

[Joss]

Just supporting the idea of isPublished() as I think it adds value.*

Talking of which....

@boudaryfunctions

I think what is likely to happen is that there will be very detailed and powerful online documentation, a solid and related API (all free to use) and separately a book that will be more aimed at less experienced users. Something like that.

In addition - all help is needed on the Wiki as a really good starting place for the moment to get things down somewhere!

Joss

(*I have noted that it is now mandatory to make some reference to the original post... however cursory that might be)

[Pete]

My thinking was that a PDF of the book could be free, but since we're not even started on that idea yet it's not a concern at the moment