Posted on: 09/15/03 03:03pm
By: emagin
I would like to suggest we begin a formal documentation effort for GL, along the lines of what
Gallery is doing.
We can then start a group effort to creating a serious and clear documenation. Right now everything is focused on administrators, *nix and hacker. I suggest we put all that good stuff in there, but then broaden the thing to include:
Newbies
Win32 admins
and add a whole section on
End Users USING the darned thing for General Users who have no idea how to use HTML tags, upload files, ftp, etc.
This could be the \"public\" version of the documentation, whereas the other part is for admins installing GL
We should have some structure to this thing (TBD of course) but maybe a rough idea could be (heavily cribbed from Gallery example):
Preface
1. Installation Guide
Overview
Features
Credits
Installation Requirements
Installing on a Unix/Linux Server with FTP
.. with Shell Access
Installing on a Windows Server (Apache)
Installing on a Windows Server (IIS)
Upgrading
Additional Help
Frequently Asked Questions
Plug-ins
Hacks
Blocks
2. Administration Guide
Basics
Securing your OS
*nix
win32
GL Security and Permissions
Backup and Restore
Creating an Offline Copy
3. User Guide
Basics
Your user rights
Forums
Calendar
Etc.
.....
4. GaDeveloper\'s Guide
Introduction
Function Reference
Concepts
Patterns
Modules
Layouts
Themes
Support
5. Guide Standards
Basics
Formatting
Generating the manual
Layout of the Documentation
Naming Conventions
Other Tips
Re:GL Documentation - Formal Effort
Posted on: 09/15/03 06:15pm
By: lcox
I commend the desire for great user docs for GL. Given your interest, I wanted to show you a framework that I started awhile back.
GeekLog Tutorials @ mindfab.com
I was using RoboHelp as the authoring tool to do this prototype documentation.
I don\'t consider this so far along that it needs to be salvaged, or the RoboHelp tool be required if there\'s a better way to go about it. I do think it can serve a prototype purpose of setting the \"level\" for the user docs. Levels include detail, target audience, quality.
Some documentation project requirements I see are:
Multiple contributors - tools so many can easily jump on is key. Though I started some docs for purposes of supporting our clients and sharing them with the community, good, complete docs takes many more than one or two contributors.
Quality - I would like to see a professional looking piece of documentation. Maybe I\'m alone, but I think a lot of Wiki\'s look like hacks and seem cluttered, but perhaps I don\'t understand enough about how you envision the role of a Wiki. Is it just for the collaboration piece, and we can get a full-up set of docs out of it (standalone - see below.)
Standalone - Would be nice to cut a set of docs on a version to be distributed with the GL tars and integrated into GL at least such that the links to the docs come off the same domain/host where GL is being hosted (vs requiring internet access - need to be able to host the docs internally, behind a firewall.) Standalone in that the output doesn\'t need a dynamic framework behind it.
Multiple formats - online/HTML and PDF are the two main ones I think should be supported.
In any case, GeekLog is a great piece of software and deserves great documentation, so I am glad to see others interested in kicking up a GL doc project. Hopefully, the ideas above and the prototype at the URL above might jump start some of the effort.
Thanks,
Landon Cox
http://www.mindfab.com
Re:GL Documentation - Formal Effort
Posted on: 09/15/03 06:55pm
By: Blaine
You won\'t find anyone that will argue the need for more user and admin documentation. It\'s been talked about often but little has been contributed to-date.
I believe the best format to create the docs is a wiki - what we need is content at this point. An HTML version can easily be created and distributed with the archive. Reformat the content later is easy once the content exists and then anyone running a business can produce PDF\'s and hardcover if they want.
We need:
An environment that will allow others to contribute easily to add/edit online
An organized Table of contents (TOC)
User and Admin Manual instances
Any examples need to be generic and not using client or user sites
Someone assigned as editor and oversee the documentation project
The gallery and XOOPS project have a good TOC
here and can be used for reference.
We can setup a wiki at wiki.geeklog.net or docs.geeklog.net - that\'s not the issue. Its getting someone to volunteer as the lead that has some experience creating documentation and volunteers to create the content. It\'s having someone leading this and following through. I\'d do it - but already have too many geeklog projects.
Re:GL Documentation - Formal Effort
Posted on: 09/15/03 08:24pm
By: lcox
Hi Blaine, I agree with your needs list.
I don\'t have any direct experience setting up and/or running a Wiki-based doc project, so I have to trust you know how to turn a wiki-based site into standalone HTML. Maybe it\'s as simple as spidering it, I haven\'t looked into it.
Assuming there is a reasonable path from Wiki to standalone HTML (and PDF for future), I\'m game. I think it would be a good exercise to take the prototype content I developed and stuff it into a Wiki-based system to see how it works and looks. It sounds like it wouldn\'t take much to set up the wiki - if it\'s agreed to go that way, I can take a shot at plugging in existing prototype content and graphics. If it gets set up on geeklog.net, let me know and I\'ll put some stuff up.
Landon
Re:GL Documentation - Formal Effort
Posted on: 09/15/03 10:26pm
By: TechFan
Sounds like a great idea. That structure at mindfab.com would be great for the online documenation. It works very smoothly and look professional. Of course, we also would want the docs to be easily converted to different formats.
Re:GL Documentation - Formal Effort
Posted on: 09/17/03 03:14pm
By: emagin
Icox why don\'t you head up the project again.
I can take the lead on Win32 side of things, if that is seen as warranting it\'s own section in the Docs or addendums to each section within the docs.
I agree with Blaine that initially it should be about CONTENT.
First let\'s gather all the darned info, then we can pump it out as nice HTML. Once you have the text, dressing it up via CSS or some other form is not that hard.
Most important in my mind would be:
Multiple people having access to update quickly
A simple but clear TOC / hiearchy that we can add to
Follow basic guidelines to entering info
Before porting over too much stuff, let\'s set up
#5 Guide Standards first, so that we can all agree on how to proceed.
PHPWiki can deal with graphics, I believe.
Your mindfab RoboHelp stuff is very cool.
Robohelp costs $ right?
Who owns the license, what happens if you go away, what do we do, etc. If that can be resolved easily, then let\'s go with RoboHelp.
I have a feeling that since GL is an opensource PHP / MySQL app, many people here would want the docs to follow in that tradition. Might also make it easier to \'port\' the whole documentation Wiki INTO a GL plugin later, should that be seen as valuable.
Let\'s get started, I\'m game to manage a piece of this.
I\'m running a dual processor xenon box *but* running win32 Apache with 256kb upstream. If you want I can set up PHPWiki here, unless we have better solution via GL servers, RoboHelp, etc. then let\'s do that.
Re:GL Documentation - Formal Effort
Posted on: 09/17/03 03:43pm
By: Dirk
Just for completeness and since nobody mentioned it in this thread yet, I\'d like to point out the documentation started by
rawdata:
http://www.doyourdd.us/
And it\'s even using a wiki ...
bye, Dirk
Re:GL Documentation - Formal Effort
Posted on: 09/17/03 11:18pm
By: ScurvyDawg
Cool Thanks Dirk thats a great site. Very well done.
Re:GL Documentation - Formal Effort
Posted on: 09/18/03 01:03am
By: emagin
I just got a long reply from Maka, who set the site up with a friend.
I\'m hoping they\'ll join this discussion to see where we go from here, but they seem quite open to a group effort, are just concerned the licensing language keeps it open for personal use but not for commercial resale.
Re:GL Documentation - Formal Effort
Posted on: 09/18/03 10:32am
By: tomw
Some advice for the documentation project.
I applaud the effort. I have found that the person who writes the code is not the best person to write the documentation -- they already understand what is going on and fail to document what they consider obvious.
For the project to work, someone needs to step up and take charge. Without a clear driving force, it will not get done.
The person who steps up to do it, needs to recruit helpers. Don\'t wait for volunteers, you won\'t get many if any. Contact people directly and say, will you do this part? Strictly volunteer documentation does not work very well.
Set up a ambitious time table and keep pushing, else you documentation will be out of date before its done.
Get buy in from those who have done the documentation before and incorporate their work.
Ignore critics -- they never get anything done.
When are you going to quit talking and get going? Who is going to take charge? If you are waiting for Dirk or Tony to empower you forget it, they have better things to do.
TomW
Re:GL Documentation - Formal Effort
Posted on: 09/19/03 08:39pm
By: emagin
Ok, I think we are ready to rumble.
The guys at
DoyourDD survived the hurricane and will be posting instructions on how to sign up and have at it for documentation effort.
I\'ll start posting docs updates and notes as I have time.
As I mentioned, I\'m a win32 user, so I will focus on making a parallel or sub-index for win32 specific issues.
I have a feeling it would make more sense to keep the docs index hierarchy simple and focused on GL in GENERAL, and just have subsections for OS issues under the main GENERAL sections, so that we don\'t break this document up too much into OS chunks that then become unwieldy and separate.
I think it\'s best to keep it all together so that changes in a GL docs section will inform the OS specific stuff \'below\' it.
Re:GL Documentation - Formal Effort
Posted on: 09/20/03 12:58am
By: DTrumbower
Feel free to use the database
diagrams[*1] . If you need better or different formats let me know.
Re:GL Documentation - Formal Effort
Posted on: 09/20/03 04:35am
By: ScurvyDawg
There is another GL documentation site. I do not know what the authors will want to contribute but I thought I would bring it up.
They may have info that has not been written elswhere, I have not done a thorough examination or comparison, but it looks good. Because they have done some branding a few chages will be needed but its all there.
www.mindfab.com/tutorials/
Re:GL Documentation - Formal Effort
Posted on: 09/20/03 01:09pm
By: emagin
Scurvy, this site was mentioned above, I think.
They are using RoboHelp, which is very slick, but costs serious bucks. So that raises questions of long-term future shareability from a hosting perspective.
What\'s interesting about the MindFab folks: I think they are the guys who are providing consulting services packaging GL solutions with other custom apps to business customers.
So if they are involved in the effort, there may be some areas where their needs are more specific than a general GL community, but certainly they have done good work there.
I\'d recommend we go with the PHPWiki implementation discussed above.
Re:GL Documentation - Formal Effort
Posted on: 09/20/03 03:37pm
By: lcox
Yes, I\'m not suggesting we standardize on RoboHelp for the very reason cited - it\'s costly and therefore limits the people who can contribute.
I am concerned, though, that the Wiki will not meet the needs of normal end-users of the doc if it\'s doesn\'t look like quality stuff and is not very tutorial-oriented.
We need to make sure this Wiki doesn\'t end up looking like a glorified FAQ otherwise it will still not be what I was after when I started the tutorials at MindFab.
Here\'s the rationale I was working under. Audience: A lot of the users we serve in the mainstream, if they found geeklog.net, would be completely lost. Keep in mind, geeklog.net is not short on content, so while I think some focus should be put on getting good content up quickly, the amount of content is not the issue - it\'s the amount of organized, good-looking, tutorial-oriented content that\'s in short supply.
When I think of tutorial oriented docs I think of step-by-step, heavy graphical content with very consistent, templated content. If I were to sit down with a novice admin, how would I teach them to mange their site?
So, anyway, that\'s partly why I went with RoboHelp at the time, developed some of the step-by-step templates, and partly why I\'m concerned with the Wiki approach.
I have yet to see a Wiki that isn\'t almost 100% text....very minimal graphic content. As I\'m short on experience with Wiki, I\'m genuinely asking: Why are so many Wiki\'s practically all text? I haven\'t really spent a lot of time hunting down good Wiki examples, but the ones I\'ve seen are not what I would be looking for in mainstream user docs. If you have some good media-rich Wiki examples, I would love to look at them and follow that lead.
One example of a Wiki problem that will bite us before we get far, and again, I\'m focusing on the end result vs the process it supports of getting there, is that the outline is not collapsable...it\'s essentially a hierarchical list of links. I could easily imagine GL outline in a Wiki being many pages long. In other words, just from the outlining point of view, the end document is not very easy to work with or navigable.
I like the idea of a Wiki mainly because of the ability to involve many people and I can definitely buy into the practicality of \"something is better than nothing\", but I\'m underwhelmed by the actual results I\'ve seen w/r to professional looking documentation. I don\'t know if that\'s a Wiki limitation, especially with supporting embedded graphics and good HTML/styles, or whether most Wikis just don\'t have that much time put into them to focus on good cosmetics and instructionally sound content. I guess I\'m just going to have to spend some seat time on Wiki and find out.
Another thing I was wondering about was whether this documentation effort should eschew a Wiki and integrate something directly into GL - this would include building some tutorial-oriented presentation templates and authoring forms along with the simplest of php to render the help directly into the GL page when appropriate - I\'m thinking: online help that conforms to the current GL theme, is searchable with the GL search engine, and so on.
If Wiki wasn\'t sitting out there tempting us with ultra-fast results, wouldn\'t we want an integrated help system especially since GL provides so much of the infrastructure, (including a multi-contributor model, templating, andn searching) that\'s needed to do what we\'re doing?
In any case, I wanted to explain a little more about what I\'m looking for in end-user docs and why - particularly the audience (people that have a mainstream use for GL but aren\'t geeky enough or intimidated to hang out on this site to get all their questions answered.)
I definitely want to contribute what I have to the effort, but I would hate to think we\'re painting ourselves into a corner where we trade quick results for weak-looking content that\'s hard to use and get around in and later requires a lot of HTML translation to buff up into something professional-looking.
Food for thought. Comments welcome.
Landon Cox
MindFab
Re:GL Documentation - Formal Effort
Posted on: 09/20/03 03:38pm
By: ScurvyDawg
OK, Very cool.
I like what you have to say Icox.
The work you have done so far is great and I like that you want to focus on the end user not the administrator for the site or server.
I look forward to seeing this come together.
Re:GL Documentation - Formal Effort
Posted on: 09/20/03 03:44pm
By: lcox
Also, I want to offer up our GL demo site for this effort if it\'s needed. We can \"unbrand it\" easily.
For all the doc graphics, we should probably pick a single site and theme to capture snapshots from. Whether it\'s our demo site or not, I don\'t care.
Re:GL Documentation - Formal Effort
Posted on: 09/20/03 04:53pm
By: emagin
Hey guys, this is getting kind of complicated:
- We need docs! Let\'s get content first, then worry about format. Hey, if it has a TOC, search and images, that\'s enough!
- Robohelp is proprietary. PHPWiki is free/open
If wiki is not good enough, what\'s the concrete, working alternative. No way we are going to code a Docs plugin AND do docs at the same time!
- PHPWiki link I sent you earlier has plenty of
GRAPHICS.
- The only thing it does not have is collapsibility. Ok, but come on....
- For single site screenshots, I\'d suggest Geeklog.net until 2.0 comes out
I\'m starting on PHPWiki unless I hear of a better alternative that we can implement immediately. Otherwise we\'ll just drag on forever.
Re:GL Documentation - Formal Effort
Posted on: 09/21/03 08:05pm
By: lcox
Having good quality docs is important and that includes format or it will be wasted effort and/or create more work. If we keep that in mind with a Wiki, it will probably be just fine. So, I\'m game and we\'ll see if it hits the mark. Sounds like you\'re setting it up, yes? Let us know when it\'s ready since you sound like you\'re moving on it.
As far as using geeklog.net for the screen-caps, that doesn\'t seem practical to be giving admin rights out to people who want to doc admin features. Some of these docs will need to show the results of changes to config.php - geeklog.net is a production site and isn\'t appropriate as the target site if we are exposing a bunch of the admin features of GL. Don\'t you agree? That\'s why I offered up a sandbox site we can use unless there\'s an existing sandbox subdomain on GL.net that could be used for these purposes.
Lets keep a high-bar on the content and I think it will meet the needs of mainstream admins. I truly believe quality not just quantity is critical to help mainstream this software and get more people into using it. Looking forward to getting this underway.
Re:GL Documentation - Formal Effort
Posted on: 09/21/03 11:43pm
By: Blaine
Sounds like your making progress on the approach. Can you please also use generic screen images that will help familiarize the user with the base install as well.
We should not include personal or client screen snapshots if this is going to be a common set of user and admin docs.
Re:GL Documentation - Formal Effort
Posted on: 09/22/03 12:04am
By: emagin
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?
Re:GL Documentation - Formal Effort
Posted on: 09/22/03 11:51am
By: rawdata
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:
<?plugin RawHtml
>>>>> add any tags you want here <<<<
<img src=\"http://www.domain.com/graphic.jpg\" height=\"xx\" width=\"xx\"
align=\"middle\">
>>>>> add any tags you want here <<<<
?>
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.
Uploading Images
Posted on: 09/22/03 02:22pm
By: emagin
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.
Re:GL Documentation - Formal Effort
Posted on: 09/22/03 04:16pm
By: lcox
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.
Re:GL Documentation - Formal Effort
Posted on: 09/22/03 06:14pm
By: rawdata
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/
Re:GL Documentation - Formal Effort
Posted on: 09/22/03 09:46pm
By: Euan
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.
Re:GL Documentation - Formal Effort
Posted on: 09/22/03 11:48pm
By: lcox
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.
Re:GL Documentation - Formal Effort
Posted on: 09/22/03 11:59pm
By: lcox
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.
Re:GL Documentation - Formal Effort
Posted on: 09/23/03 12:34am
By: lcox
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.
Re:GL Documentation - Formal Effort
Posted on: 09/23/03 02:41am
By: lcox
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.
Re:GL Documentation - Formal Effort
Posted on: 09/29/03 12:10am
By: Blaine
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
Re:GL Documentation - Formal Effort
Posted on: 10/22/03 04:29pm
By: Blaine
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[*2]
Re:GL Documentation - Formal Effort
Posted on: 12/09/03 02:50pm
By: exaurdon
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[*3]
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...)
Re:GL Documentation - Formal Effort
Posted on: 12/11/03 11:19am
By: exaurdon
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~
Re:GL Documentation - Formal Effort
Posted on: 12/11/03 03:32pm
By: Tony
I have found that the person who writes the code is not the best person to write the documentation
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).
Re:GL Documentation - Formal Effort
Posted on: 12/11/03 04:10pm
By: amckay
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.
Re:GL Documentation - Formal Effort
Posted on: 12/11/03 04:16pm
By: emagin
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
[QUOTE BY= Blaine] You will find a nice TOC and layout that the XOOPS team has been using for their docs. This section
wakka=InstallGuide">here [/QUOTE]
This Doc system is WakkaWiki which needs tweak to support
Images [*4]
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[*5]
I looked at
PHP Documentor[*6]
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
Re:GL Documentation - Formal Effort
Posted on: 12/11/03 06:18pm
By: amckay
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
Re:GL Documentation - Formal Effort
Posted on: 12/11/03 06:29pm
By: amckay
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
Re:GL Documentation - Formal Effort
Posted on: 12/11/03 09:57pm
By: samstone
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
Re:GL Documentation - Formal Effort
Posted on: 12/11/03 09:57pm
By: exaurdon
Thank-you for be willing to put some work into the documentation. As soon as you have a home for the docs, please post it here so i can start contributing....
Exaurdon~
Re:GL Documentation - Formal Effort
Posted on: 12/12/03 08:12am
By: tomw
[QUOTE BY= amckay]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.
[/QUOTE]
I spearheaded the plugin programming guide and Blaine and I did most of the writing. That was my final major contribution to the Geeklog Project with work dragging me away. The plugin documentation is in bad need of updating, Blaine mentioned a while ago he was going to work on it. I do not know if he has done any work on it. I would contact him first, but as far as I am concerned you can take it and run with it.
By the way you are all wimps, I made the plugin documentation with Joe from the command window on my linux box in pure html.
TomW
Re:GL Documentation - Formal Effort
Posted on: 12/19/03 10:05am
By: Turias
Alright, guys, let's get this ball rolling. Do we have webspace for this, yet? How about a wiki?
These are the easy things. It's getting everyone to contribute to the documentation that's hard.
Re:GL Documentation - Formal Effort
Posted on: 12/19/03 10:51am
By: Dirk
[QUOTE BY= Turias] These are the easy things.[/QUOTE]
Also, maybe you'd like to try some other form of communication, like a mailing list or IRC. Feel free to use Geeklog's resources (the geeklog-users or geeklog-devtalk mailing lists would come to mind; there's also #geeklog on irc.freenode.net).
bye, Dirk
Re:GL Documentation - Formal Effort
Posted on: 12/19/03 11:18am
By: emagin
Hey TomW, if you say people are wimps, then you can't expect help.
I think what a few of us in this thread have said is:
Make it easy for people to contribute, and they will join the effort.
Make it an arcane, pseudo-programming effort, and you will only get programming types, who are busy enough working on plug-ins
I am still searching for a wikki that does easy image uploading TO the server. If you choose something like most regular Wikkis, then you will lose people like me who are visual and need to see screenshots in docs for them to be read and followed.
I guess it depends on the type of docs you want to create (programmer/admin or end-user) and who's going to create them.
I'm adding IRC now and am subscribed to GL user / dev lists
Re:GL Documentation - Formal Effort
Posted on: 12/19/03 12:55pm
By: Turias
[QUOTE BY= emagin]Hey TomW, if you say people are wimps, then you can't expect help. [/QUOTE]
He was only kidding around.
[QUOTE BY= emagin]I am still searching for a wikki that does easy image uploading TO the server.[/QUOTE]
I've been looking a little, too, and it seems that most sites that do this don't have images uploads incorporated with the wiki. Instead, they have a page with a script used to upload images just somewhere on the site. Then, later they can link to the images in the wiki just by writing the necessary HTML.
[QUOTE BY= emagin]I'm adding IRC now and am subscribed to GL user / dev lists [/QUOTE]
I'm also subscribed to the lists.
Re:GL Documentation - Formal Effort
Posted on: 12/19/03 08:19pm
By: Anonymous (a)
MoinMoin has image uploading
GL Documentation - Formal Effort
Posted on: 02/05/04 10:49pm
By: destr0yr
Has anything else happened with this formal docum. effort? Converation seemed to die back in December...
GL Documentation - Formal Effort
Posted on: 03/01/04 01:12am
By: Anonymous (neonsurfer)
I've been following this thread also. I was wondering the same thing. Anybody?
GL Documentation - Formal Effort
Posted on: 03/01/04 01:22am
By: emagin
I've been unable to find anything that meets my personal needs to easily handle images in documentation.
ehelp (macromedia) RoboHelp sure is fun and easy to use, but it costs a fortune.
So for me personally, I've opted to use a separate GL install to handle documentation via stories and static pages. However this is unwieldy as the content grows without some indexing capability.
Sorry, but we are not moving along very much here.
GL Documentation - Formal Effort
Posted on: 05/18/04 10:10am
By: Blaine
Maybe you should look at WikiMedia - the Wiki that is used to develop online encylopedias and dictionaries.
It is a Wikie with Media Extensions see the
featurelist[*7]
GL Documentation - Formal Effort
Posted on: 01/31/05 04:46pm
By: emagin
I've found the perfect tool to do what I need but in another CMS!
It's called
WiwiMod[*8]
It's perfect because it's:
Simple Wiki with 3 minute learning time
Incorporates HTMLArea for wysiwyg editing
Allows for image upload to directories on server
Has a dynamic table of contents
It's reallly great, unfortunately only for Xoops but I'm using it.
GL Documentation - Formal Effort
Posted on: 01/31/05 08:44pm
By: vinny
GL Documentation - Formal Effort
Posted on: 01/31/05 08:55pm
By: Blaine
emagin: Are you currently contributing to the formal Documentation effort?