Translations Available (click a flag to view):
Help Discussion Archive
Items deleted from the Help Discussion page can be archived here.
The Development and Maintenance Factory is designed for use in large KGS help page development and maintenance projects. It may also be useful for small projects.
The factory is new and quite small right now. It provides a flexible framework that is easy to understand, easy to expand, easy to change, and easy to contract.
One component of this factory is the Help Editor's Manuals and Guidelines. These manuals and guidelines are linked from the help page Hot Links through the Help Editors Information link. The links are at the bottom of the HEIL page, so you have to page down to get to them.
The guidelines document conventions designed to introduce a greater degree of uniformity in the KGS help pages than they used to have. These conventions have been incorporated into the KGS help pages. This is especially true of the "Page Formatting Guidelines"
Another component of the factory is the sandboxes. This is currently comprised of the five sandboxes: sandbox, sandbox2, sandbox3, sandbox4, sandbox5. It also includes the JIT test page. Not a big deal to package together by any means, but a useful package to have.
Another component is a Configuration Control Archive System. This is completely new. It is a place to archive code that you are about to delete from the help pages but you want to keep around for reference use. Pages that you are going to unlink from the KGS help page system can be linked directly into the Archive Index. Sections of pages that you want to save can be cut and pasted into the HelpPageArchive. You can make a new archive for many sections saved from a single help page, such as the HelpDiscussionArchive used for sections from this page, and link it into the Archive Index.
The CCAS also contains a Templates page that has such useful templates as
- Under Construction warning
- Major Update warnings - both for source and sandbox - with a bi-directional link.
- "Please delete this page" template.
- Table of Contents template.
The CCAS even generates an error message for the most common mistake in using the Major Update warning, namely forgetting to replace the YourHelpPage.html item in the template with the name of the source file for the major update.
The front door to the factory is the "Help Editor's Resources" page. It is a collection of hot links to the various components of the factory and to other KGS help page items to which it is useful to have quick access. For example, there are hot links to 1) reference pages and 2) utility pages.
1) Reference Pages
Like the statistics page, code examples page, and the automatically generated "list all pages" page that lists all the English pages and their links.
2) Utility Pages
Frequently linked to, edited, or examined help pages that are clumsy to access through the KGS system. Pages like toc.html and underConstruction.html.
The "Help Editor's Resources" page is currently referenced in the Hot Links. The hot link to it is located in the Help Editor's section at the bottom of the Hot Links list.
DeaconJohn -- 23 August 2010 -- McMahon Pairing Variants
Yet another new page.
DeaconJohn -- 23 August 2010 -- The Help Editor FAQ
Another new page.
DeaconJohn -- 23 August 2010 -- Please check out the new Newbie FAQ page.
DeaconJohn -- 23 August 2010 -- Server History Page
Deleted reference to the "server history" page from the "main" page. The server history page is now redundent with the history of KGS given on the sensei library.
DeaconJohn -- 23 August 2010 -- A Net Etiquette Implementation Problem Page
This page looks like it should be deleted, but that is not the case.
This page looks like it should not be linked to from the English FAQ, but that is not the case either.
This page has been split into two pages (1. "chat and emails" and 2. "playing a game") and a third page (3. "watching a game") has been added. These three pages are referenced directly from the English FAQ page.
If you click the "list all pages" button, you see that the English FAQ page is the only page referencing the Net Etiquette page (except for this "HelpDescription" page). These things make it appear that this page should be deleted.
However, this page is also referenced by non-English pages (at least some of which are written in English or a mixture of English and other languages). These links are not mentioned when "list all pages" is clicked. This is probably a bug in the KGS software.
Deleting this page would break these links, and it is not currently possible for me to tell how many of these links there are. I have found just a few by accident. It is alos possible that the third-party KGS clients (like the ones for the Asian languages) may reference this page.
In addition, this page is referenced by the English FAQ page even though that reference is redundant. This is to provide easy access to this page for maintenance purposes.
In other words, this page is nothing but a "precursor" or a "wrapper" and it would be nice if it were practical to delete it. Maybe someday the KGS software servicing the "list all pages" button will be upgraded and this will be possible.
This explanation is referenced in a leading comment in the Net Etiquette page and it is also referenced in a comment in the English FAQ page. If this text is deleted, please update those comments.
This implementation difficulty was caused by a problem in the current version of the KGS software. The workaround described in the above text is further explained in the "Tips and Tricks" section of the Help Editor's FAQ.
DeaconJohn -- 12 March 2010 -- See moonpig's new bot page. It is really nice.
DeaconJohn -- 20 Febuary 2010 -- Hot Links
Added the title "Hot Links" to the "table of contents" page.
This change is intended to make it easier to refer to the links in the toc. For example, it is now possible to write, "see the 'McMahon Pairings' help page in the 'Hot Links' section that appears on the right of every help page".
Used the title "Hot Links" instead of the title "Table of Contents" because "Hot Links" is both more descriptive of what's there and is easier to write.
DeaconJohn -- 5 Febuary 2010 -- "My First KGS Help Page"
A newbie help page editor tells the story of the creation of his first KGS help page.
Introduction
The phrase "McMahon tournament" in the announcement for the February KGS Plus McMahon tournament totally confused me. My best guess was that a McMahon tournament was a memorial tournament held in memory of someone named "McMahon."
A quick google search yielded a Wikipedia article on the subject. However, even after reading it, I still didn't grasp the basic concepts. I needed a more elementary explanation. The Wikipedia
McMahon page linked to the Sensei
page on the same subject. The Sensei page was helpful, but I still needed a more elementary explanation.
Next I searched through the KGS help pages, the French KGS FAQ pages, and a few of the old KGS tournament records. I still did not find what I was looking for.
It finally occurred to me that a good way to get a better grasp on the basic concepts of the McMahon system would be to write a KGS help page explaining it. Maybe I this would help me understand the McMahon system. And, it might save others from having to repeat my less-than-satisfying web search.
In the past, I had only done very minor editing on the KGS help pages, much less create a new help page from scratch, so this would also be a good opportunity to learn how to create one. As an additional bonus, I could "brush up" my HTML skills a little bit.
What a pleasant suprise I was in for!
The KGS Editing Tools
The KGS editing tools were a joy. They made all the mechanics of working with HTML easy. No need to create my new page and then try to link to it. No need to fool aouend with the messy header stuff. KGS created my page for me automatically, just like it's supposed to.
The instantaneous page preview feature in the KGS help page editor (combined with the HTML error checking capability) made it easy for me to avoid those nasty little HTML syntax bugs that can be so frustrating.
At one point I was moving some text from another (obsolete) page into my new page and the text got lost along the way. There had been an HTML error report that I missed. I had put the text into my KGS text box, had seen it in the preview, had done some more editing that introduced an error, the KGS editor had (correctly) not updated my page, and the text had been lost. Thanks to the well-constructed KGS change histories, I was able to recover the lost text immediately and move on.
I even had the satisfaction of offering a new tool to the KGS help editor community, namely the "Under Construction" help page.
Naturally, I learned a few things about the KGS help page editing process. Two of the most important to me were as follows.
1) The Importance of Using The Dot (.) for the edit description of continued edits.
I did realize the importance of this technique early enough and I left behind a trail of messy edit descriptions that I have no way to clean up. These are displayed under the "recent changes" link in the toc page for anybody to see. That is a little embarassing, but, it will be gone from the public view and forgotten within a week or two.
2) The usefulness of the "List all Help Pages" link in the KGS page editor.
This serves the purpose of the "site index" that many sites have but KGS does not. Let's face it, it's not trivial to find one's way around the KGS help pages. Having this feature is a nice "perk" for volunteering to be a KGS help page editor.
In addition to providing you with a nice alphabetical "site index," the list of all help pages gives crossreferences. In other words, it tells you all the help pages that link to each page. Even better, the crossreferences are updated instantly while you are changing the links in the pages. This really helps you keep track of what is going on while you fooling around with links between pages.
So, there was no significant difficulty working with the mechanics of the KGS HTML editing facility. In fact, there was not even an mildly difficult learning curve - one just figures it out as one goes along.
Writing the stream-of-consciousness text was a joy as always.
WordSmithing
Next came the hard, but satisfying, work of bringing the text up to the usual standards of good technical writing.
The Final Result
The result is an initial release of a piece of text (McMahon Pairings), ready for others to correct as they see fit. The satistaction that I feel is kind of like the satisfaction that you have when you make the alpha release of a piece of software that you have just created. You know that it still has bugs, but, you hope that others will find it useful.
DeaconJohn -- 4 Febuary 2010 -- The "Under Construction" Page
An "Under Construction" page has been created. Please feel free to use this page to assist you in creating and editing help pages. For example, it might be useful when you are using the KGS editing mechanisms to create a new page and when you don't want anyone else to edit it while you are working on it. Elementary instructions to use it for this purpose are as follows.
1) First, put a link to your new page in an existing KGS help page. Your new page will automatically be created and inserted into the list of all help pages in the usual fashion.
2) Next, change the link in the help page to point to the "Under Construction" page. Your new help page will remain in the "all help pages" for easy access with the KGS web page editor.
3) When your page is ready for its initial release, change the link to the "Under Construction" page to point to your new page.
Edit this page (requires admin or translator privilege)
