Geeklog Forums

Ok, so I think we have it then: 1) PHP Wiki Let\'s give it a shot for say, 3 months, and see where we get. Icox, you can be the usability critic and keep it real. If we get off track, and it\'s not usable enough for general public use, we\'ll salvage content and discuss plan B with better interface The current best solution is the PHPWiki that MakaMaka set up at http://www.doyourdd.us I am working out access now. 2) Geeklog sandbox Icox, I think your idea is good to set this up. So we set up a generic, vanilla install, and whoever sets things up to document should leave a note as to how long they leave it up so they can finish docs on it, before it is swept clean again. Don\'t forget, I\'d like to do a win32 section, so I\'ll be doing that on my own servers when necessary to explain win32 nuances. 3) Skeleton Outline Let\'s set up a skeleton outline in the new PHPWiki as soon as it\'s available. I think this part should be a bit of a free-for-all for the first week, with discussion to decide where to go as we do it. Otherwise we\'ll be in forum threads all day and never get this thing off the ground. A touch of improvisation / extreme programming approach to this thing (just in the beginning) might be nice so we can see the breadth of what people have dreamt up before we start slapping some meat on it. The original skeleton I had in the first message of this thread was my 3 minute typing session, I would guess everyone can rearrange and add/subtract what they want in the Wiki til we can close the brainstorm session and start documenting. What do you think?

emagin contacted me saying some here are interested in creating docs. A friend and I were slowly working on some in a Wiki. Anyone is invited to join in if you want. I've modified the script to take a database back-end to allow others to use it as well. If you contact my friend with what username and password you would like to use we'll add you if you've been a registered contributing member here. It actually can be opened up completely, but since we're giving admin privileges we're restricting access to logins this way. To address some of the concerns here. There are a number of free and commercial editors one can use to create documentation some of which are definitely better than Wikis. The main benefits of a Wiki though are: 1) it's a tool for collaborative work, 2) it's far easier than many of the other products for the average person to learn, and 3) almost all of them are completely free. They are in no way a high-end help document creator and do have limitations. The one we set up is PHPWiki. The reason we chose this one was unlike many of the others, it allows pages to contain plain text, any HTML tags, as well as PHP code, or a mixture of all three. Can you insert graphics? Yes. All it requires is placing the URL inside square brackets like this [http://www.domain.com/graphic.jpg] or use HTML tags like this: Can it have a collapsible menu? Yes...but it requires writing a PHPWiki plugin to give this effect because none of the default plugins do this. The TOC for one document could indeed end up several pages long just like in any book. It could also be written where the upper TOC is high level and each section displays the sub-menu of its content instead. Alternatively, one could create the same effect that RoboHelp has using frames with a javacript menu. Such menus are great, but they tend to slow down (loading and changing) significantly as the number of links it has to deal with increases. Also, most js menus do not work cross-browsers or in those with js turned off. In which case, they will also appear as a very long TOC. Why are so many Wiki's practically all text? Because most are totally open to the general public to freely post on. Many of them also do not have the capability to handle HTML/PHP or severely limit this access due to security concerns just like we do on Geeklog. I doubt you'll find many, if any, media-rich Wikis because they are mainly used for the very simple markup language for collaboration purposes. Webpages are literally filled with HTML tags which makes it very hard and slow for the average human to read and edit. Wikis were designed with a simple language to make this faster and easier. They were also developed before any WYSIWYG editors were made for webpages. They were never created with the intent to develop feature rich HTML pages though a few today will handle the tags. Those who have used Wikis for documention usually don't insert graphics. I don't know why since many have this capability and it definitely aids understanding. Then again, a lot of docs are not written at the level of the intended audience. The one we're using can have literally anything that can go into an HTML page but to do so requires admin access. The more you stick to the simple markup though, the easier it will be when you or someone else goes back and reedits. By all means, please take the time and do a search to see if you can find something better that doesn't cost a lot of money and can be used by multiple people or even develop something GL tailored. We're not attached to PHPWiki. It's just a tool to help put info together. A Wiki is definitely a poor cousin to many editors, but I'll tell you that hasn't stopped different people from trying to suck up the entire site almost every day (and thus get banned as well) even though it's not anywhere near complete. If anyone here is guilty of doing such activity, please stop because this is one reason we haven't gone faster. After the doc is in a somewhat decent shape, it will be made available for download.

The only thing I worry about with posting images is that we can\'t be limited by URL references. Otherwise our images will be scattered all over the place. We need a central repository of all text and images, so we need to be able to upload images up to the server the Wiki sits on, preferably in one fell swoop like we do with GL Submit Story. To FTP first, then make a link to an image, etc. is too cumbersome and will discourage images in the docs.

I\'ll be \'unbranding\' a demo site that can be used front and back for the doc project. Our current demo site is at http://demo.mindfab.com but I need to strip it down so it\'s appropriate as a base GL site for the doc project. When I get that strip-down done, I\'ll take requests for admin privs to the sandbox site.

It currently has no image upload capability, and it also has no feature to tell where exactly to place an image after it\'s uploaded. The former could be written as a plugin while the latter would require making changes to its parser whose code I\'m not familiar with at all. It has a capability to upload content to be inserted into a page and to upload dumps to re-populate the database. I agree it would be nice to have an image upload feature, but I\'ll be honest I have too much on my plate right now to take on the coding for that. Since this sounds like a show stopper, why don\'t you just do a search and see if there is a better product to use. Perhaps you\'ll have better luck finding it than we did. As for the demo site, this is good for content filler: http://www.lipsum.com/

There\'s an ErfurtWiki plugin running on http://euans.net/blog/ - if you want to try that out for the documentation project, feel free. Just register and log in to access. You could use the Ewiki Plugin when lcox gets his site running - it works fine, and you can restrict access to GL user groups.

---

-- Heather Engineering
-- No job too small

Ok, I\'ve stripped down our demo site: demo.mindfab.com to have pretty much no content. It\'s not a stock install because it has both file mgt plugin and the forum plugin running. Caveats: It\'s running 1.3.7 and we should upgrade it but I want to change the db password first. This upgrade 1.3.7->1.3.8 may be something we want to doc while we\'re doing it? If desired, we can scratch this thing completely and start with a completely fresh 1.3.8, no plugins at all. Also, as a matter of course, when we (MindFab) install GL sites, we have a modified set of all the standard and many non-standard themes - mainly the mod is to get the site logo from a consistent location within the theme layout, so rather than modifying every logo of every theme, right now just XSilver and Clean are on it. During the 1.3.7-8 upgrade all the standard themes can get reinstalled. If you want GL admin access to the site for purposes of contributing docs/screenshots, send mail to helpdesk@mindfab.com. At some point in the near future we\'ll figure out who all to give full admin rights to for configuring config.php, etc. As this is a scratch site, don\'t put content into it you want to save - it could get whacked. If you are documenting something and have a specific piece you\'re in the middle of, communicate that to us. I don\'t think it makes sense to put the wiki plugin into this as this is a demo site for screen shot purposes not as the repository for the docs themselves. ---- Finally, I\'m wondering if it might make sense to create a documentation GL that uses the story and GL database for the documentation repository instead of wiki. This has many advantages and overcomes some of the limitations of stuffing a wiki including some of those mentioned above. Then write a tool to yank it from the GL db into a good format that\'s navigable (page-turning, tree nav, etc.) The stories themselves from the raw db become the content for the docs. An outline outside of GL controls which stories go where and wraps the content with navigation. That way we can get as much content up and running fast, including stuffing in graphics, as we would with a Wiki, but without its limitations. We use GL to help doc GL. We\'re going to end up writing some custom stuff anyway if we do wiki. I\'d rather see us use GL itself as the core tool to store content and then our customizations apply to GL instead of Wiki. I\'ve looked at several promising Tree/Menu systems that are PHP-based. Take a look at: http://www.chipchapin.com/WebTools/MenuTools/ Also: http://www.chipchapin.com/WebTools/MenuTools/phplayersmenu-2.2.0/ There\'s tons of OSS code that could help us put out decent tree navigation.

Should mention also that there\'s a standard de jour for expressing outlines in XML, called OPML, http://www.opml.org/ Even came out of the blogging community...think it was a Dave Winer thing if I remember right. Outline processors such as OminOutliner can export to it. Would be interesting, especially given its blogging roots, for our docs to use it. Will put up some examples of it later.

See: http://www.mindfab.com/tutorials/GLDocExample.html for an extremely crude example of using an outline based on OPML to point to documentation/stories that reside in GL itself. It also has a link to what OPML looks like. It can get more sophisticated by adding columns to an entry which become attributes to the xml tag for the item. Three quick refinements to the concept are 1) frame-based - outline lives in left frame, content target in right and page turning nav in an upper above the content. 2) instead of a static outline as in this example, the outline is expandable/collapsable based on some of the OSS PHP tree code listed above. We walk an OPML outline and generate the tree code 3) instead of pointing to the stories as rendered in GL itself, rip the GL db to render the story HTML as a standalone page this brings it back straight to using GL as the document repository and even authoring tool we all know and love. The main point is that we can use GL as the core documentation repository and wrap it with some interesting tools/components to get good, navigable content using GL itself to do a lot of the work for us. GL gives us a lot: templating, database repository, search, authoring. Useful documentation can be generated in GL while the navigation wrapper tools come together.

Spent some time with the HTML_TreeMenuXL PHP classes (see: http://www.chipchapin.com/WebTools/MenuTools/HTML_TreeMenuXL/ ) and in not much time was able to generate an expandable/collapsable outline with it using some of the existing tutorial outline I had: http://www.mindfab.com/tutorials/HTMLTreeMenuXL/gloutline.php Easy to use PHP generates nice-looking stuff. Looks like it\'s also very easy to change the skins for the outline controls.

You will find a nice TOC and layout that the XOOPS team has been using for their docs. This section here includes images for the installation. It is a wiki as well. Review the complete TOC from the home to see the install, users, admin and developers guide contents. lcox, I really like the TreeMenu Pear class, I\'ve been using it on some projects and used it on my site for the FileMgmt plugin index view. Takes a bit to figure out and then it appears simple - like most things

---

Geeklog components by PortalParts -- www.portalparts.com

I'm not sure how this effort is proceeding but wanted to post another example that I've come across. This one is a formal effort for phpnuke (gasp)

Link to site: here

---

Geeklog components by PortalParts -- www.portalparts.com

Hi All,

I just finished reading through this topic. Did anyone ever actually spearhead the formal documentation proposal? Is there any kind of offical documentation being produced? The only site that seems to be at least somewhat up to date seems to be
here

Is this the correct place to compile documentation? I've started creating updated/expanded versions of the documentation that is currently shipped with geeklog 1.3.8, and that is hosted on this site. Is there someone that would like me to submit my documentation to them?

Exaurdon~

P.S. If there is an offical external documenation effort (Beside the current html files), maybe it could have a link in the resources section of this page? (If it already has a link, I apologise in advance for being blind...)

Hi again,

I didn't get any responses to my last post, so I'll try once more... Is there any formal documentation effort going on? Has anyone taken charge of creating documentation? (Read my last post for a few more vaugely worded questions....)

Exaurdon~

I couldn't agree more ;-)

Seriously, to whoever ends up spear heading this, I would be willing to commit GL developer time to answering questions during the process but tomw is right, it's best if we don't write it.

Also, to manage it at a project level might I suggest using http://project.geeklog.net (particularly the task manager).

---

The reason people blame things on previous generations is that there's only one other choice.

I'm getting paid to write a user guide and will be happy to contribute it.

BTW, I'd suggest doing this in a Twiki. I recently used on myself for the first time - used to co-write a document with a half dozen others. I'd never do it any other way, but choice.

See my post about Twiki/GL integration, BTW. I'm happy to do it if someone can give me some pointers.

Ok, the current issue that held this thing up was agreeing on a decent Wiki or other format for storing the docs so that they:
Support easy image inclusion for screenshots
- Easy to administer
- Simple Image uploading
- Simple left index creation / navigation
- Open source
- Easily portable to another system later
- Hosting location


This Doc system is WakkaWiki which needs tweak to support Images

Mindfab is currently using Gallery to do visual tutorials, but this is a fairly limited way to do this as there is no indexing capability. Visual Tutorial

I looked at PHP Documentor
PHPWikki and WikkiWakka

None of the above seem to have very good image support, nor built in indexing that would appear on the left side like a tree index.

I am not a programmer, but I'm pretty good at organizing info and setting up servers / loading code, etc.
I will gladly host this thing if someone can advise me on a good application to run this documentation on.

Thanks

I still have not read all the posts here, but as for Robohelp, a few thoughts.

I use it at work (on my own recommendation in fact) for some of the stuff I document, but it does have shortcomings especially here. Even in an office environment it is not well suited to several people in the same office working on the same document. Having people all over the world would make it way more complicated. Not a good idea IMO.

And of course it costs 1000 bucks a pop. And sorry but I do not use pirate SW.

Wiki is the way to go, but I see there is alreayd a Wiki site so I'll be sure to sign up and start contributing.

BTW, who runs the plugin programming guide? I've been going through it the last few days, and while it is a great doc, there are a few fairly serious inaccuracies in it.

cheers,
-Alan

OK, I'm at the end and see that we are nowhere :-(

I'm willing to be the one to take the reigns. I've got lots of time in the next two months, and plan to spend a lot of it programming some GL plugins. I'll also spend some time doing docs. I do docs at work and am known for being able to do them well. Others in this thread have expressed similarly.

But I'd like to do it in a Wiki. I've set up and used Twiki and it handles images itself. But as far as that goes, let's walk before we run. If someone has a problem with this system or that - well, there will be problems with every system. Big deal. Again, let's walk before we run. Doing something even if not perfect, is better than what we have now.

Personally, I think the way to go is with the existing Wiki system. It's there, let's use it. Not sure if it does graphics, but who cares? We can get someone to set up a place to put all graphics and we can link to them from there.

Does the existing Wiki allow uploading of graphics?

If not, emagin, can you set something up?

cheers,
-Alan

I will chip in with documentation. I will be busy util mid Feb, but will start working with you guys right after that.

Why don't we just get started, with Wiki or whatever. Since they are all text, I don't think it will be hard to transfer when we find a better program.

Sam