Documentation Concept

[MatthewSchenker]

Greetings,

The question of documentation has come up in a few different places here, as it is vital to the success of this terrific application. I really like the existing documentation, which is very effective at helping people get up to speed on ProcessWire. At the same time, I've been putting together my own personal documentation on ProcessWire, mostly to remind myself of steps. It is turning into something that might be useful to others...

The way my material is shaping up, I believe, is complementary to the existing documentation. It's naturally arranging itself as a series of "examples" of using ProcessWire, or specific "How To..." entries. Then inside each entry I am free to branch into references of whatever parts of the API are relevant for that examle or "How To" entry. For whatever reason, this approach seems more appropriate to ProcessWire.

Just my opinion, but I think the best framework documentation is for CodeIgniter. That one goes class-by-class. What it lacks, I believe, is a thorough set of example uses.

I'm planning to put together a Web site that will house these examples and "How To" entries, and I will make reference to the existing API. I'd also like this to coordinate with other documentation projects that other members are working on.

How does this sound?

Thanks,

Matthew

[diogo]

Kendo UI has a great documentation http://docs.kendoui.com/

I also like the one from FuelPHP http://fuelphp.com/docs/

[panictree]

How does this sound?

It sounds like a fantastic idea, Matthew, and I certainly agree that Codeigniter has some of the best documentation I've come across with, so it could act as an example to aspire to. In my opinion, and as Soma mentioned in another thread, the main problem novice users face when looking for information is that, more often than not, they don't really know what to look for, so the odds of them finding the right info are pretty slim. I really believe that having 'how-to" articles that address a wide array of different case scenarios would help diminish this problem, and make the current documentation more beginner friendly.

The small project walkthrough tutorial that Ryan posted some time ago is a superb example of how this can be implemented. This tutorial helps ProcessWire newcomers understand how the most basic actions are executed in the system, and provides information that will be of use in projects that go far beyond the scope of the case study Ryan proposes. I can say this tutorial helped me understand the system.

In my opinion, ProcessWire's documentation is already quite good, but I think, looking at the future, we should go the extra mile to make things easier for those users with less experience with PHP. As it turns out, the number of designers using ProcessWire seems to be growing, and this can only be regarded as a good thing. Adding a collection of project walkthroughs, or how-to articles to the documentation, be that through processwire.com or through any other website, is going to make ProcessWire much more attractive to a much wider audience. This is just my opinion, anyway.

Claudio

[MatthewSchenker]

Hello,

Thanks panictree for your great response...

I'm looking into a couple of things on this right now, and also studying some model sites that I think do a great job with "how-to" arrangements.

I'm collecting my documentation now into distinct routines. Hope to have some news soon!

Thanks,

Matthew

[Joss]

Looking at a couple of the examples above, I quite like the Kendo UI landing page.

The four big buttons immediately make you react depending on your ability and/or experience.

That is important for any documentation I feel.

I have always liked the idea of layering things starting with the simplest answer first:

What is a domestic cat?

Layer 1: A small Furry animal

Layer 2: A small predatory mammal of the cat family

Layer 3: A quadruped of the family mammalia and species Felidae that is commonly kept as a domestic pet ....

And so on. Basically the idea is that the first level answers a question with a solution rather than a full explanation, but each further layer adds more to the detail of the explanation for those who want or need to know those details. But if you are not interested, Layer 1 would give you and answer and possibly something you can copy and paste.

I have to admit I have never actually tried out this idea ... but I have been talking about it for years!

[Joss]

Editing my wiki tutorial (I mean my tutorial on the wiki, not about it), I was just thinking about linking in advance of having a page.

On Mediawiki, you can link to a non-existent page which at least might prompt someone to go and create the page, assuming they see the red link.

On Google Sites you go one stage further. When inserting a link, you can choose from an existing page, or create a new page. Choosing the latter option creates the page then links to it - though you are not taken to the page and the new, empty page is not flagged up.

This sort of functionality is very useful, but I think could go even further.

So, you are writing an article and want to cross link it to another article that does not as yet exist.

1. You use the linking system and like Google you can either link to an existing article (or category too), or create a new article.

2. You give the article a name and (optionally) associate it with one or more existing categories. (In PW, you probably also choose a Template or it falls back to a default template)

3. The article is created (and the link completed), but it is flagged as an Empty Article automatically - maybe made a member of an Empty Article Category.

In the admin area (or where ever the article writing is taking place) a list of empty articles is kept - nice and prominent so that contributing authors know they need to be worked on.

The same flagging should also apply to any articles where the author is looking for help or a collaborator and so on.

Joss

[onjegolders]

Looking at a couple of the examples above, I quite like the Kendo UI landing page.

The four big buttons immediately make you react depending on your ability and/or experience.

That is important for any documentation I feel.

I have always liked the idea of layering things starting with the simplest answer first:

What is a domestic cat?

Layer 1: A small Furry animal

Layer 2: A small predatory mammal of the cat family

Layer 3: A quadruped of the family mammalia and species Felidae that is commonly kept as a domestic pet ....

And so on. Basically the idea is that the first level answers a question with a solution rather than a full explanation, but each further layer adds more to the detail of the explanation for those who want or need to know those details. But if you are not interested, Layer 1 would give you and answer and possibly something you can copy and paste.

I have to admit I have never actually tried out this idea ... but I have been talking about it for years!

I really like this idea, I think CodeIgniter is a sort of benchmark for quality docs http://ellislab.com/codeigniter/user-guide, not only is it layered in a similar way to how you mention, but also the page is so easy to read

[MatthewSchenker]

Hello,

As I mentioned in my first post, I definitely see CodeIgniter as a model for documentation. The other framework that I have been using for some projects is Laravel, and it also has terrific documentation (http://laravel.com/docs).

Still, I think both CodeIgniter and Laravel do not have enough illustrative examples of how the code is used for day-to-day real tasks. That's what I want to base my documentation on. I've already written several pages for my project, and I have high hopes for it. My longer-term goal is for it to link up with the work others are doing -- for example Joss's material.

I'm putting together actual documentation pages now, and also a scheme for the way the whole thing works. I'll present it soon.

ProcessWire is such an amazing tool, it elevates your whole idea of what's possible. That in turn is making me want to create documentation that is also amazing.

Thanks,

Matthew

[diogo]

I really like Linode's documentation http://library.linode.com/. I always found what I was looking for, and their tutorials are straight to the point and easy to follow. And we are talking about something pretty complex here...

[lucas]

Whoa, Matthew, that would be so *incredibly* useful! Specially for PW/PHP beginners like me...

I really appreciate you taking your time for doing this! And I'm sure many others will too!

[ryan]

I've always liked the CodeIgniter docs too, though haven't had experience with the others, but they also look nice. I found this rather humorous though:

http://ellislab.com/codeigniter/user-guide

Note the lack of a trailing slash in the URL above (copied from onejegolders post). Click it, and then click "table of contents" and click on any item in there. You will get to a page with some Arnold video. Apparently EllisLab hasn't accounted for the trailing slash vs. non-trailing slash.

[FuturShoc]

For the record, I have a friend who works at Ellis. They've just fixed the trailing slash issue on the CI documentation.