Geeklog Forums

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

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

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.

---

Geeklog components by PortalParts -- www.portalparts.com

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

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.

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.

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

Cool Thanks Dirk thats a great site. Very well done.

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.

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

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.

Feel free to use the database diagrams . If you need better or different formats let me know.

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/

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.

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

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.

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.

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.

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.

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.

---

Geeklog components by PortalParts -- www.portalparts.com