Vanilla Tutorial/Documental Site

hbf · February 2012

Jongos said: @hbf

> .php.source-php .de1, .php.source-php .de2 {
>     background:none repeat scroll 0 0 transparent;
>     font:1.0em/1.2em monospace;
>     margin:0;
>     padding:0;
>     vertical-align:top;
> }
>

changing the font line to 1.2em/1.4em monospace seems to make it at a nice size.

and one more problem, the long lines not wrapping.

just add "white-space: pre-wrap;" to the css.

done.

I continue to be amazed at the progress you guys are making on the content.

clethrill · February 2012

Only just noticed this, happy to help out where and when I can

hbf · February 2012

clethrill said: Only just noticed this, happy to help out where and when I can

@clethrill feel free to jump in and modify / add content where ever you can. Don't worry about starting things you can't finish, it ok. others will help round out content. just capture what you feel is important.

hbf · February 2012

and the path to the wiki is

http://www.homebrewforums.net/vanillawiki/

just posting it again so you don't have to search through this thread to find it.

Jongos · February 2012

@hbf

some padding would be nice. to the code box would be nice.

same css selectors. padding : 12px;

hbf · February 2012

Ok

Jongos · February 2012

hehe.. it's blue now! I'm loving it!

been thinking about it too but thought too much to ask.

nice!

hbf · February 2012

******** NOTE *********

I've moved the wiki to a new address.

http://vanillawiki.hombrewforums.net

this should be a more user friendly address. The old address still works, but i recommend you begin using this one, as eventually I will retire the old one.

Jongos · February 2012

designers and developers section almost cover all that's covered in the official doc site.

I'm doing quick guide on writing application as i am making one. along the way will fill in infos on all the main classes (API section) as i read them to understand applications. Already covered Gdn_ApplicationManager.

will need reviews and corrections.

hbf · February 2012

Jongos said: designers and developers section almost cover all that's covered in the official doc site.

I'm doing quick guide on writing application as i am making one. along the way will fill in infos on all the main classes (API section) as i read them to understand applications. Already covered Gdn_ApplicationManager.

will need reviews and corrections.

i've been trying to review as i notice new content. mostly making typographical corrections. you're way ahead of me on the technical content.

422 · February 2012

Cannot get to your new url three posts up, is it live?

hbf · February 2012

422 said: Cannot get to your new url three posts up, is it live?

yes, it's live for me. please try again, maybe the DNS just hasn't updated on your end?

Is anyone else having trouble reaching the new address?

hbf · February 2012

AH.... Typo in the post!!!

http://vanillawiki.homebrewforums.net/

I was missing the 'e' in 'home'

my mistake!

hbf · February 2012

i would edit the original post but, alas, i can not.

Jongos · February 2012

Can't decide the best way to document a class....

How do we want a class documented?

Presenting all info in table form or should the table contains only the basic info and the rest in it's section?

If in table form, the space might be restricted.

If all method is in their own subsection, might be a bit harder for brain to digest (that's how it seems to me). And a method prone to be left out when checking it's validity after a new update is available.

like, an important methods (those commonly used, esp. those in Gdn_Controller) might need a good elaborate explanations and examples.

x00 · February 2012

I wouldn't re-invent the wheel. Code documentation should be done with code documenting software.

Wiki should be more about how to, but teaching general php is a bit beyond its scope. However the code doc could be linked.

There is already in-line documentation, although some of it is incomplete, and occasionally incorrect, a code documenter should be able to pull this out of the code base.

x00 · February 2012

phpBB3 uses PHPDoctor for documenting its code debase. This might be an option, or some other.

Jongos · February 2012

Regarding the Classes :

reason i want to cover classes in the wiki :

I've already made a doxygen doc (i shared a download link in this forum), but a lot of methods is missing inline documentation. I had to include source code to it, but then it's hard to read. Try generate one or download the one i shared. It's helpful in visualising the relationship between classes but not in describing what a class/method do.
Methods/params that I don't understand or is not so clear what it's about even after jumping from file to file, hopefully someone would explain in plain term. Setting a breakpoint in debugger and try to trace thru trace stack is very time consuming. Add sample output, etc.
It's a wiki, anyone can contribute. You dont have to have access to hbf server filesystem to edit the docs, unlike a generated docs.

I'm not expecting the whole Garden library would be documented, just the fundamentally important ones that matter to most apps and/or plugins.

Regarding PHP :

I guess you're talking about the Help for Learning Programmers, it's just merely to tell them that such a concept exist.

It's from my own experience, trying to learn OOP & Framework and stuck again-again in 10 years, because it simply didn't register to me that concepts of software pattern etc. exist.

So when i tried to learn stuffs like Joomla, I went like "wtf, what kind of code is this, how can this work, just when do the classes got instantiated?" simply because I didn't know there was such a thing as Factory pattern and that is not covered in any OO book I've read. No one cared to say "joomla use the factory pattern in".

It's not gonna teach much, just links and excerpts, and how it is applied in Vanilla.

When i say "Learning Programmers" it includes me, and i put it so i could put my notes/bookmarks to share with others.

x00 · February 2012

http://stackoverflow.com/questions/3052036/how-to-include-custom-files-in-doxygen

Jongos · February 2012

@hbf

can you please add this extension, http://en.wikipedia.org/wiki/User:MarkS/Extra_edit_buttons

inserting code/small/pre/ tags manually repetetively is quite irritating...

hbf · February 2012

Jongos said: @hbf

can you please add this extension, http://en.wikipedia.org/wiki/User:MarkS/Extra_edit_buttons

inserting code/small/pre/ tags manually repetetively is quite irritating...

im looking at this but it doesn't really appear to be a plugin. I'm not sure what to install. I'm seeing that it requires user level js to be run, im not sure of the security implications there, but it sounds a little risky.

tannerc · February 2012

this RULES, thank you so much

x00 · February 2012

Looking good.

This is just my opinion, but I would not spend too much time on general programming information which has been written about time an time again. Instead find great resources, and link to them. Keep to one or two paragraphs, if you can.

Time is a premium.

General rule of thumb with wikis, is consolidate until you have to split. There isn't really a need for several pages on general programming, just have one page, and use headings.

I would take a look how other forums do their documentation. Especially forums that are heavily OOP. If not forums something equivalent. I would automate as much as possible. If you can get some schematics from the team that could help you with how to structure the documentation.

Two things that are need off the bat, are general documentation (not articles), and some "How to"s.

I would prioritise on the starter to intermediate stuff, due to the way things are interlinked on wikis. The advanced stuff, will come with time.

Jongos · February 2012

hbf said:

Jongos said: @hbf

can you please add this extension, http://en.wikipedia.org/wiki/User:MarkS/Extra_edit_buttons

inserting code/small/pre/ tags manually repetetively is quite irritating...

im looking at this but it doesn't really appear to be a plugin. I'm not sure what to install. I'm seeing that it requires user level js to be run, im not sure of the security implications there, but it sounds a little risky.

okay.

Actually I was looking for something like this, a bookmarklet : http://simile.mit.edu/wiki/Wiki_Table_Editor

where a user need to bookmark a javascript, and when he's on a wiki edit page, he just click the bookmark and the table edit buttons will appear.

tried to convert MarkS into bookmarklet, but too long....

It's okay... I'll look for other alternative.

Jongos · February 2012

x00 said: Looking good.

This is just my opinion, but I would not spend too much time on general programming information which has been written about time an time again. Instead find great resources, and link to them. Keep to one or two paragraphs, if you can.

Time is a premium.

General rule of thumb with wikis, is consolidate until you have to split. There isn't really a need for several pages on general programming, just have one page, and use headings.

I would take a look how other forums do their documentation. Especially forums that are heavily OOP. If not forums something equivalent. I would automate as much as possible. If you can get some schematics from the team that could help you with how to structure the documentation.

Two things that are need off the bat, are general documentation (not articles), and some "How to"s.

I would prioritise on the starter to intermediate stuff, due to the way things are interlinked on wikis. The advanced stuff, will come with time.

digesting...

x00 · February 2012

There are also a lot of question that have already been asked, but are not easily found, if you can find a good answer link to it, copy parts of it.

hbf · February 2012

x00 said: There are also a lot of question that have already been asked, but are not easily found, if you can find a good answer link to it, copy parts of it.

this is something i've thought about a bit. i think copying the best parts is the key, otherwise you could link to something with pages and pages of non-sense, but some very insightful nugget buried somewhere...

it would be good to have help in flagging the insightful stuff so it can be edited and added more efficiently.

hbf · February 2012

usage has dropped off significantly in the last couple of days.. Would it be appropriate to get better visibility for this asset by creating a sticky or even a permanent link somewhere here?

I'd hate for this resource to languish because people just don't know of it, or this thread falls of the main page and the whole thing ends up "out of sight, out of mind"

I'm dedicating server resources for this, and asking nothing in return, which i'm perfectly happy with as long as it's being used.

Jongos · February 2012

So that means the site usage is mostly from editing and adding contents.

I haven't been able to continue because of some commitments.

will be back..

and the wiki still is linked from only two websites.

@hbf, have you registered the wiki at google for indexing?

x00 · February 2012

I think hbf is right, need to select posts that are clear, and answer questions definitively.

If you have a format for this perhaps a "Related discussions" section at the end of of the article/stub. As this is not an encyclopedia, but a help wiki, citations aren't the focus, but a list of related information would be a help.

Howdy, Stranger!

Categories

In this Discussion

Vanilla Tutorial/Documental Site

Comments