 |
Is there Documentation Dungeon?
Is there a documentation dungeon? I think so. I've spent countless hours working to unwind what I can only call a complete documentation disaster. This blog is a tale about how open docs can go wrong. It all started a few years back when we selected the MediaWiki software for our DocBase open document system. No, we weren't all that excited about that choice, and the gurus debated it for a couple weeks. Finally, just to get things started, we proceeded with it, mainly because MediaWiki was available and fairly mainstream (e.g. Wikipedia is based on it.) Gabriele Santilli got it set-up and running in just a few days. In the beginning I took the first swipe at organizing the content of DocBase. Although not perfect, it was fairly easy to find what you wanted and navigate around. However, over the years the documentation was modified and reorganized. On the surface it seemed ok. Pages were subdivided and new index directories were built by members of the community. I was happy... because users decided to participate. But, I started to have problems finding the content I wanted. At first, I thought it was just me -- that I didn't understand the structure. As a result, over the last year, I began to avoid DocBase altogether. I couldn't find anything. Eventually, I created the R3 Doc wiki (based on the REBOL WIP Wiki) and centralized all R3 core documentation there. It's easy to use and manage; the organization is pure and clean. There's no MySQL to mangle all the content and hog all the memory, and if I need to do something complex like batch modify a group of pages, a simple REBOL script works well. Over the last few weeks, with the GUI project powering up again, it became necessary to review and cleanup the DocBase GUI documentation. I figured it would take me a few days. That is: two or three days. I started looking at DocBase more closely... and, frankly, it looked more like a bunch of pages dropped in a blender and mixed on purée. What a mess. It was document mismanagement on steroids. Well, it's not been pleasant, but I've managed to sort out a lot of what I needed related to graphics and the GUI. And, the new pages are no longer in DocBase; they are now located on REBOL.com. Take a look at R3 GUI as a starting point. Yes, there's still a bit more to do -- in a few more days. So, I've learned a few lessons about open systems... but, this was perhaps the hard way to learn them. At least I can now be positive about where we go from here. I can actually read and use the GUI docs again. Yeah!
|
 |
Updated 12-Mar-2024 - Copyright Carl Sassenrath - WWW.REBOL.COM - Edit - Blogger Source Code |