Improving Documentation - Smarty / Embedding is too hard!

[garvinhicking]

Hi!

Today I've got a PM by a user who told me that the way of embedding s9y into an existing webpage either via the Embed-method or Smarty is not at all to understand for new users. Thus I replied that I would love to see documentation effort put into this area.

Who is willing to help make this possible, an easy "Smarty HowTo". From users, for users. I think I am often explaining much with keeping technical things in my mind or expecting users to know Smarty already, thus I am not open-minded enough to really make this all happen. I know you guys can!

Here's our conversation:

[garvinhicking]

Hello Garvin:

First of all thank you very much for all your hard work on serendipity. I look forward to using it very much.

However I feel I must let you know about something that maybe no one else has told you about.

The process of embedding the serendipity app in an existing page is incredibly difficult. I know that you apparently do not believe that, based on various statements you have made in these forums. I have worked with various programming languages for 5 years now, and I can tell you that it is definitely extremely difficult to customize a template for serendipity.

Please do not take this as an attack, or an attempt to get something from you in any way. I am not the kind of person who goes around looking to start a fight, and I also have nothing to gain personally by sending you this PM. I am only letting you know this because I want to help you, and the online world.

The documentation on how to use the smarty system is nearly useless. The description of how to set the preferences correctly in order to have serendipity show up embedded inside someone's web page (with that person's formatting) is equally useless.

Again: please do not take this as an attack on your work. I'm sure that you have worked a long, long, long time on serendipity and would like to see as many people as possible use it, right?

So I recommend that you ask someone you know, who knows a little bit about web design, to try to install serendipity on their web server and customize serendipity so that it is embedded on that person's website.

I recommend that you sit silently in a chair and watch them, and give them NO advice beyond what they can find themselves, WITHOUT your help.

Try to remain silent behind them while they search around for the documentation. Try to stay silent as they look around on the s9y.org website for help.

It will amaze you, because you've been programming this application for so long now, and probably imagine that everyone else out there easily understands how to use serendipity as well as you do. What you will certainly see is a picture of a person who becomes so frustrated that they give up.

Without the proper instruction embedding serendipity is incredibly difficult, and believe me, the instructions on the s9y.org site are not helpful.

Again: I do not want to attack you, I only want to let you know about something that I can only guess no one else is telling you. I am telling you because I want to thank you for all the work you've given me and the world by working on serendipity and then giving it to us all for free.

I want to thank you by telling you the truth about how incredibly difficult it is to even LEARN about using serendipity.

The solution? I suggest you put up (or someone puts up) a series of pages that explain in ultra-simple steps a child could understand, the process of embedding serendipity, and/or altering the smarty files. Even steps that you think are incredibly simple and don't need to be mentioned MUST be mentioned. All of the things that you assume other people will know how to do must be slowly described, like you were telling your grandmother how to do it. That's the solution I see to the problem. And those instructions need to be in an incredibly obvious place, in a format that everyone knows how to open, such as a .doc format or .pdf.

Thanks again,
Hermes

[garvinhicking]

Hi Hermes!

Many thanks for your advice. In fact I really didn't know that you might find it that difficult. Many people here on the forum have already said how incredible easy it is to use Smarty for templating instead of PHP code in other applications, and many people have succeeded.

In my company I've seen 4 co-workers starting immediately with s9y, without my help and getting good looking results.

But that isn't the problem. The problem is you didn't succeed, and this is the starting point. Are you familar with Smarty per se? Because I do agree that our documentation is based on a view frmo someone familiar with it. We do link to the Smarty homepage for documentation on their system.

I agree that we could write up a nicer documentation. I am hands-up looking for people that help on this issue. I am not skilled at writing documentation, I am a programmer and just try to do my best with support here (as you may be able to see from the amount of my posts).

So how about you could get involved and write up a step-by-step documentation? I will offer help for any questions you have and try to add up to your text. As we have an open wiki where you could put the documentation, everyone would be free to add up to your text as well. That's in fact a great thing of opensource, that one can contribute so freely to a combined-effort product like Serendipity; it's not a one-man show and every input is needed.

I think this way we can put up a Newbie-guide-to-templating. As you may have figured out, the current way of Embedding a page is out of date, as with Smarty Templating one can do it much more easier. I think this has been noted in the docs there...

I would also like to publish your PM on the forums and ask other people for input, if you don't mind.

Thanks a lot, and no offense taken,
Garvin

[garvinhicking]

Hello Garvin:

I would love to help out by writing a step-by-step guide on how to embed serendipity into a person's web page using smarty.

Of course...I have to figure it out first! But I would certainly like to do that once I'm done customizing it for myself. So maybe in a few weeks, once I'm more familiar with using the smarty files I can write up something and send it to you for approval?

And please do feel free to post my post up on the forum.

Take Care,
Hermes

[garvinhicking]

Hi Hermes!

Thanks a lot! I really think we will be able to improve it together. Feel free to ask me anything anytime if you have problems. I'd love to help out anywhere I can. We do have a some Smarty-related forum threads, so maybe when searching for something specific that can help as well.

I'm really looking forward to this, I think a Step-by-step guide will be so helpful for users. I'll now post our PM conversation to the forums!

Regards,
Garvin

[MySchizoBuddy]

I'm a electrical engg will basic prog skills. I do understand If else statements, and what are functions and how u pass variables. I'm still confused about objects and classes

I just ported over a template of nucleus cms to s9y. and i never read any documentation (why cause i can't seem to find anything ) and i have zero knowledge of smarty as well. i just look for html and what is surrounding it in curly brackets. they r mostly if else statements along with other stuff which i dunno what they are. and i don't think i need to know. All i looked at was html and what smarty code is surrounding it.

I haven't tried to embed s9y in my webpage. If i were to do it. I would open up my html sourcecode of webpage and the one of my blog, print em out and compare em, and see what code from my blog needs to be put in my webpage and look in the *.tpl for that html code. and copy it over.

however i can see why people will find it hard to change templates. It isn't really straight forward.

[ODguru]

MSB makes a good point, in that many people learn HTML and other web technologies by looking at the code, figuring out what the individual lines do, and by stealing bits and pieces here and there and trying them out in their own website.

This works for the simple stuff like learning obscure HTML tabs and CSS syntax. However, an app like S9Y is much more sophisticated and analyzing it's code will quickly overload newbies... even for highly educated & very experienced technical newbies like me.

What would really help is a simple "real world" example, not just a block of code that leaves the reader wondering where to place it and which parts are to be edited and which parts are not.

For instance:
This site could provide a simple Index.htm with a very basic color\font scheme. This file would contain no blog... just a simple table showing site navigation links on the left, a center section with some simple text, and a right section with a few external links. A basic webpage that everyone can relate to.

Next, use that same Index.htm (I guess now it would be an Index.php and just the bare minimum of supporting files) with simple text that was shown in the center section of the original website replaced with a simple blog.

The reader would then be able to compare the two websites and see, clear as day, what was added. They would learn both syntax and implementation technique. From there, they would be better equiped to build on that knowledge and move on to more sophisticated techniques.

On a related note, when it comes to documenting the code, developers are usually one extreme (little or none) or the other extreme (so much that the code becomes hidden in a mass of \\ lines) Instead, use a few simple comments in the actual file, and then provide a supporting document that fully explains the code and why it was done like that.

With that, a more basic reader would have the more in-depth explanation (think: "s9y for dummies" book) without boring to death someone who just wants a little technical help.

During my 16+ yrs in the technology field, I've written a lot of technical documentation. Some for highly advanced techs, some for executive mgmt, and some for secretaries who just want to know how to change the shape of their "little pointing thingy on the screen"

I'd be glad to help... but as Hermes stated... as soon as I figure this out for myself.

[francisco]

This works for the simple stuff like learning obscure HTML tabs and CSS syntax. However, an app like S9Y is much more sophisticated and analyzing it's code will quickly overload newbies... even for highly educated & very experienced technical newbies like me.
....

I'd be glad to help... but as Hermes stated... as soon as I figure this out for myself.

In general learning to look at someone elses code is much more difficult than writing new code.

With 10+ years for software development and 3+ years of (mostly light ) PHP I would like to think of myself as having gone beyond newbie..

The few times I have had to look at Serendipity code I have found close to zero comments.. except for comments which are "funny" but not intended to add anything to the reader.

As much as I like Serendipity, if the current developers would like more people to help, they may want to consider helping us a little more. Having more developers involved on the long run is healthy and helps the project be vibrant and active.

[garvinhicking]

I must admit I'm not a big fan of inserting comments in code.

I only put comments in areas where something non-standard or obscure is going on, but think everything else as understandable.

I know, I should document more, but I just can't get the hang of it and always feel like everything is self-explaining. But if I were to document more, I'd have less fun on coding, so this is a compromise until someone comes along who is good at documenting code and helping this project...

I really try to add up to the documentation, but it's just like that: OpenSource development enforces what developers are interestend in: I love coding, I love adding features, I do try to fix all bugs, and I try to give good support for people who have actual questions. Anything on top of that, like documenting and designing interfaces I can only do when I really have nothing else to do. Which is very, very, very seldom the case.

Best regards,
Garvin

[Dinges]

Garvin, the only comment I was missing within the code was a definition what the functions exactly does and what the result will be and what all the parameters do. I realy miss this.

I could help you write a better doc about s9y various functions, I found out many things allready just by looking at the code, however I did not write those functions and it would be a hard time for me.


I also do not like the plugin API documentation, it is very technicaly explained, but when you first look at it: you say wtf? Maybe a tutorial could help in this area.

So if you need help writing a better documentation I could help you.

Also, the reason I chose s9y was one big drawback in wordpress: the php templates, I was allready familiar with smarty, so I quickly got irritated by those templates and saw a friends blog using serendipity and found out it uses Smarty!

[Random]

You wouldn't believe how pleased I am to see this thread running

I've kept a blog since November 2002, and a website for rather longer, but they've never been in the same place. I'm now building a site that will combine them both.

I know quite a lot about HTML and CSS, I work as a web content writer so I've used a lot of content management systems, but I've never been able to crack databases or any of the languages used to work with them, despite a lot of head scratching. Couldn't even figure out how to set up a CMS, even though I know half a dozen of them inside out as a user.

Well, finally I found a CMS I was happy with, called Etomite. Trouble is, it doesn't have a blog built in. So, on a recommendation, I had a look at Serendipity and I like it a lot. (This is the part where I say 'thank you' for all the volunteer effort that's gone into it!) So now all I have to do is figure out how to embed S9y into an Etomite-generated page.

And I don't understand the instructions...

I get the basic principle - put some PHP in the destination page that calls the output of the blog as an include. And, helpfully, in the last couple of days an Etomite user has written a code snippet designed to call an external page into an Etomite template, which takes away the need for me to understand how to set up a wrapper.php file. Had that snippet not been written, I would have been completely stuck, because I know no PHP and don't have the intuitive understanding needed to decipher what's happening in it.

Nor is Smarty going to be much use to me - I looked at it in some detail when I was researching CMSs (CMesses?) and didn't understand it, either. That's why I went for a fully-featured (albeit simple) CMS.

Today, I've managed to use the new Etomite snippet to include a fresh installation of S9y into a template page of my planned new site, which is a huge advance. But it needs a serious amount of debugging and I don't know where to start. For example, the admin page is inaccessible - it just loads the default home page of the site, which means I can't change the configuration settings of the blog. And there's a whole lot of other stuff that I need to figure out, such as how can I split out the content in the blog's side bar so that I can include it in the sidebar of my presentation template, while the blog content stays in the main content area? (I think I saw the answer to this one in the forums somewhere, so I'll keep looking - but it's certainly not in the documentation!)

And as well as the immediate practical problems, there's the more theoretical longer-term stuff that I don't get - if Serendipity's installed in a sub-directory, but the page it's embedded in is the root, how do I manage the relationship between the URIs of the static site content, and the URIs generated by the blog (eg archives) which all seem to to include the sub-directory in their path? And if a user follows a link to look at a category of posts, or part of the archive, will they stay in my site or will they be whisked off somewhere S9y-ish without my proper presentation template? I'd run some experiments, but I can't make a post because I can't access the admin area!

I'm sure a lot of these questions have answers that, to experienced developers, are blindingly obvious. But I'm an experienced web user, designer and writer - not a developer. Without proper documentation, I don't understand these things.

I obviously can't write that documentation myself, but I'm happy to polish someone else's first draft and improve its readability if it needs it.

In conclusion - I want to use this blog within my new site, and I think it will be possible to, but I don't have the technical expertise to do it. And while some volunteer on the forums might help me through my individual problems, better documentation will help the other people out there like me for years to come...

[francisco]

I only put comments in areas where something non-standard or obscure is going on, but think everything else as understandable.

To a developer his code always makes sense.

compromise until someone comes along who is good at documenting code and helping this project...

I recently started a new job which uses up a lot of my time, but I will try and help with documentation as time allows.

As it is, have already started to look at code.. at least a good 2 to 4 hours spent on the static page + postgreSQL issue.. As I get more familiar I will be able to help document some of the programs. Unfortunately, there is always that initial state of a new developer coming into a project where the person actually needs time from existing developers to learn the basics.. before he can start to contribute.

It would be helpfull if there was a blurb on how to submit suggested code changes. On the "how to help" section talks about helping with documentation, debugging etc.. but doesn't indicate how to actually submit one's work.

Should we submit diffs? Entire files? Code snippets of the functions we are suggesting to change? ??

[garvinhicking]

I tried to update the page on http://www.s9y.org/index.php?node=31 to be more precise about sending files, does that help a bit?

Best regards,
Garvin

[francisco]

I tried to update the page on http://www.s9y.org/index.php?node=31

Absolutely that definitely helps.
One more change that would make it even better is to have the line needed to do a checkout from SVN.. it also would not hurt to have a few links to some of the existing SVN clients.. or to have a separate page for that.

[ppalazzo]

On the subject of embedding, I found out by playing around with code snippets that the documentation makes it seem harder than it actually is. So I wrote an extra-simple manual to match the extra-simple way in which I solved the problem:

1. Strip the index.tpl file in the template folder of everything but the following:

{if $is_embedded != true}
{if $is_xhtml}
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
{else}
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
{/if}

<html>
<head>
<title>{$head_title|@default:$blogTitle} {if $head_subtitle} - {$head_subtitle}{/if}</title>
<meta http-equiv="Content-Type" content="text/html; charset={$head_charset}" />
<meta name="Powered-By" content="Serendipity v.{$head_version}" />
<link rel="stylesheet" type="text/css" href="{$head_link_stylesheet}" />
<link rel="alternate" type="application/rss+xml" title="{$blogTitle} RSS feed" href="{$serendipityBaseURL}{$serendipityRewritePrefix}feeds/index.rss2" />
<link rel="alternate" type="application/x.atom+xml" title="{$blogTitle} Atom feed" href="{$serendipityBaseURL}{$serendipityRewritePrefix}feeds/atom.xml" />
{if $entry_id}
<link rel="pingback" href="{$serendipityBaseURL}comment.php?type=pingback&entry_id={$entry_id}" />
{/if}

{serendipity_hookPlugin hook="frontend_header"}
</head>

<body>
{else}
{serendipity_hookPlugin hook="frontend_header"}
{/if}

{$CONTENT}

{$raw_data}
{serendipity_hookPlugin hook="frontend_footer"}
{if $is_embedded != true}
</body>
</html>
{/if}

(You might be able to strip something else off it but that's how it worked for me).

2. create a content file where you put the following lines at the beginning:

<?php
ob_start();
require 'index.php';
$blog_data = ob_get_contents();
ob_end_clean();

# The following command redirects users who arrive at your website to the blog, if no other instruction is given

if (!isset($_REQUEST['page'])) {
$_REQUEST['page'] = 'blog';
}
?>

3. Compose the page as you wish, with css and all.
4. Where you want the blog entries to appear, write the following command:

<?php
if ($_REQUEST['page'] = 'blog') {
echo $blog_data;
}
?>

5. Add plugin elements to anywhere on your content page with the following command:

<?php
$title = '';
$plugin =& serendipity_plugin_api::load_plugin('@serendipity_archives_plugin:7a7a61eba0e221525617534f68752f46');
$plugin->generate_content($title);
?>

Note: this is the only place where you have to edit the command. Replace the string in italics with the plugin name from the serendipity_plugins database.

I'm sure it will have to be edited for code redundancies or other errors I might have made, but this seems to work on my testing server.[/i][/quote]