Comments on: 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!
22 Comments Comments:
Jonty
11-Mar-2010 14:08:24 |
MediaWiki ... unfortunately many are led into that dark trap 'well WikiPedia uses it'.
I still struggle to find stuff too on our work one - and it has far, far less info than DocBase! It's search abilities are woeful, and organisation ends up being ... pureed mess as you say.
Ugh!
| Ippokratis
11-Mar-2010 14:34:36 |
Do you think CouchDB could serve the purpose of a docs indexer ? My knowledge in IT is fairly limited but seems to fit (I'm not an affiliate). I also noticed that Ingo Hohmann recently ported a CouchDB client in Rebol http://www.rebol.org/view-script.r?script=couchdb3.r
| Kargyle
11-Mar-2010 16:30:38 |
Its the nature of the beast. Although the pages "Styles" & "Faces" are well written, Rebol documentation continues to be quite linear, characterised by lengthy scrolling pages. There does not seem to be a central management control that links to the different sections.
Such a control might be added to each page, or perhaps a Rebol Plugin Script might be used, or even a Rebol Script could be used to gather web pages to user hard drives and present them from text-lists of chapters and subjects. That would likely reduce the hits on the Rebol site, but.... Perhaps the Rebol script could be a community project, or a contest just to see what ideas might surface.
A central system might be even a pie shaped image with up to 6 sections linking to say 6 core areas of Rebol. Possibly this would bring a sense of cohesion to the maze.
...are these Google Adsense images I see when viewing Rebol.com an intentional thing, or is there something else happening here?
| Gerard Cote
11-Mar-2010 19:12:16 |
Great rework Carl,
This new R3 Gui documentation is filling the gaps I had noted in the previous effort (event if I don't master the deep knowledge required to add new styles myself)
Since for the last few days I was studying some R2 scripts and your new information will help me getting deeper knowledge.
For example, with what I already got in the past, yesterday I was finally able to successfully adapt the simple animation tutorial from Carl Read - http://www.rebol.net/cookbook/recipes/0047.html to fit the recent requirements of R2 Draw dialect.
The main source of how-to information for this was found from the running R2 Draw example I got from Nick's http://re-bol.com/rebol.html#section-9.4
Other nice small examples can be elaborated from his ideas to complete both the actual cookbook and word browser you put in place first. I plan to help you in some near future with this task.
In the same spirit, as I plan to submit the new revised draw-based animation script for newcomers please could you tell me where I have to post it.
In a second trial I also began to study Anton Rolls' scripts related to diagram drawing (as you requested some program to replace MacDraw here a few posts ago).
So this morning I began my deep study of the intermediate 2 scripts referred below and I must admit that for the second one, the interactive one for which Anton added some modified style, the previous original doc was missing some deep info about that.
But your new doc is now just providing it to me. In fact I now know about this since I had read Henrik's own doc (VID Extension Kit - Style creation) and it then gave me some lengthy explanation about the process.
But even then I was not ready yet to catch this deep info. Now seeing it in action, combined with your new doc gives me some additional cue about what goes under the hood ...
Nevertheless before I will able to do it myself will require more deep study.
But at least now there seems to be a better way to get the needed information than solely studying the VID/View source code itself - without having a prior understanding of both the global and specific view of what is required ! IMHO.
You're on the right track to successfully embrace the clarity goal you are aiming to, as far as I can see it now.
Congratulations and my thumbs up to you for what you already accomplished up to now. Really a great enhancement!
FYI here are the links (available from Rebsite) for the 3 Anton's scripts I went studying into lately ... this could serve as a basis for a guided experiment or more deep REBOL info !
Thanks Carl, Anton, Henrik and every other REBOL Guru for your good work and for letting us share your work.
REBOL Data structures illustrated (without context info)
anton.wildit.net.au/rebol/doc/rebol-values.r
REBOL-View animated-event-flow
anton.wildit.net.au/rebol/doc/event-flow-diagram.r
Simple Interactive Diagram Editor
anton.wildit.net.au/rebol/doc/bubble-doc.r
Henrik's Style Creation Doc (main link)
97.107.135.89/www.hmkdesign.dk | shadwolf
11-Mar-2010 21:17:02 |
I'm glad you get the same feeling about documentation in REBOL than me and that's not new that I say the documentation is missing depth.
Carl imagine that i made color text widget (area-tc /viva-rebol) research work with only surface documentations. 70% of the actual work I don't understand it ... Sounds incredible or hard to believe but that's the truth...
I know by saying that i'm not providing any solution to the documentation depth problem, and for that I'm sorry ...
| tomc
11-Mar-2010 22:23:17 |
(good) documentation requires more structure than a wiki supports. Absence of responsible for that structure gets developer types to write any documentation at all. We are doing the same thing and even with "policy" based best practices it still devolves into a pile of random isolated facts. I suspect there is a niche between wiki and strictly enforced hierarchical doc manager but I have not found it. | Greg Schofield
11-Mar-2010 23:35:43 |
For what this is worth, I found it almost impossible to get to grips with the old docs on GUIs. Anything I did do happened by accident or from copying things already working.
I actually understood the new R3 docs, I can write GUIs using this and I mean seriously before I was always shooting in the dark. In may need depth as others were saying but it has got clarity which the others were missing.
Whatever was done, should be built upon. | Graham
11-Mar-2010 23:52:39 |
Open source has little to do with the necessity to have an editor who overseas the organization. I think you have to take some responsibility for the outcome when you abandoned the wiki. | Steven White
12-Mar-2010 8:45:19 |
I am relieved to know that I am not the only one who had a lot of trouble with the R2 GUI documentation. Maybe I'm not as dumb as I thought I was. What I miss is something like railroad diagrams or BNF. For example, something like a section on BUTTON, with every construction that could possibly appear after the word BUTTON. Something like that for every "sytle." I do realize that this might not be possible with REBOL, just because so many facets are common to so many styles. But without some sort of organization that tells me what I may do, or what I must do, or what I should do, I can't seem to put together something more than a simple GUI, usually by copying something from elsewhere. I still am a beginner, though, so my comments should not be taken too seriously. | -pekr-
12-Mar-2010 9:56:29 |
Steven,
that should be possible, just look into RebGUI docs, they are listing all possible facets/attributes/parameters. It also seems to me, that VID3 is much more cleaner, so looking into particular style source is already self-explanatory, altough you probably will not see facets, which are inherited from parent style ...
So far I am quite satisfied with how VID3 docs start to appear ... | Hostile Fork
12-Mar-2010 13:02:34 |
Long time no comment, but...blaming MediaWiki for Rebol's documentation is like blaming Microsoft Notepad for why you can't write a Grammy Award winning screenplay.
I wholeheartedly agree MediaWiki is not a profound piece of software. It is not a semantic database, and it is written in the saddest of sad web technologies (PHP). (Look to Freebase or StackOverflow if you want to see something with actual technical merit...)
Yet still: The failure to document and formalize features in advance of their implementation—or to develop evangelists within the community who do not burn out—this is the essential problem for Rebol. Anyone with half an hour can learn MediaWiki, it has built-in version control and diff which is central and drives its crowdsourcing success.
But for crowdsourcing, you need a crowd. Rebol has been the leather-jacketed language in the corner who doesn't need friends because it knows its cool and doesn't need to prove it...but...as a consequence it's missing out on the cafeteria dialogue.
Though I've been working on various non-technical projects the past few months, programming always brings me back to Rebol's essences. Like many others, I remain curious and enthusiastic...we all wonder when the isolating "cave" will really turn into the festive "bazaar".
When will my advice about cohering the visual communication, logo/theme, and marketing message be heeded? What do the current graphics on the homepage mean and signify to someone trying to build an impression of what this project stands for?
When will "Ha, Twitter was down in the last minute, it could be done in 10 lines of Rebol...such a disgrace" be supplanted with the proper humility and respect for the non-language-related engineering it takes to scale such a service that Rebol has never had enough users to even breathe upon?
These are the questions I ask, I stand ready to help--and I hate PHP too but c'mon. It's like they say: "the carpenter who blames his tool is not a good professional."
No blame, no excuses, no posturing. We are the generation and we have the opportunity: Let's fix software. | Brian Hawley
12-Mar-2010 15:30:57 |
I don't think he was blaming MediaWiki, so much as recognizing the consequence of the access rules of the particular MediaWiki installation. It's possible that the access rules were inherent in MediaWiki, but that would be something for an expert to answer.
As for documenting in advance of implementation, that would be nice but it isn't always possible. If you are refining the design as you go along you can't always know ahead of time what the final design would be. That has definitely been the case here. REBOL projects are often like that: It is so easy to implement things in REBOL most of the time that the implementation phase is almost formality, and writing the design docs can take longer than implementing the design, particularly for the core code.
Another problem was that some of the people who were contributing to the docs didn't know the project, and so combined the documentation for two entirely separate GUI systems, resulting in a real mess that was formatted nicely but made no sense. And there were more problems we don't need to get into here.
It's not MediaWiki's fault, it's a lesson about open systems: Use better access controls. | Graham
12-Mar-2010 16:04:35 |
I thought the open source rebol book had a better structure and that's because Henrik took ownership of the structure when he started it.
http://en.wikibooks.org/wiki/REBOL_Programming
| shadwolf
12-Mar-2010 20:12:12 |
hum how are done the gpl other languages documentation?
i'm sorry but lua ruby python have the same documentation needs as we in 2 layers
first the developer's what you need to know toimprove the language
Second the what you need to know to build your own softwares based on that language.
documentation quality is a key point main concern and not only for rebol.
I remember having read several time the author and community of ruby annoncing a reorganisation of documentation all along those past years.
for rebol since all was concentred in carl's hands we concidered it was better to let carl comming with the main documentation fount and we added some very sêcific documentation to present a short sample of how to use a specefic part of rebol. We called that articles. Even the book from olivier averlot is more a succession of articles presenting the rebol plural technologies than a deep explaination on how far you can go in a particular field of rebol. when i was new to rebol i used that book alot but then going deeper i meet the need to exchange experiences with others rebol programers and i learned a lot more thru that way. but then that experience gain wich feets my own needs is not driven into a documenttation others could use. I tryed alot to come with kind of documention in that optical but doing it as a hobbie i failed to produce the docs i wanted to do...
and doing docs maybe involve a talent i don't have...
| shadwolf
13-Mar-2010 16:30:08 |
maybe a good ide would be to mix an forum system (ability to send message delete theme est or a track like rambo ) and a wiki.
Ok here is the maine idea. I read a documentation in Rebol-doc.net or what ever. I find this documentation interresting but not answering the point i want to understand.
Then the same way i post comments on this blog i can submit a comentary without needing to access to the document and mess it up with anotations. So all the comments on a specific documation are separated but accessible easyly to anyone. Ofcourse those free comments are able to be managed pined etc bu the redactors granted group. that way when the redactor group realise the comment then this comment change state becomming
from a comment to a work in progress to a document changelog entry.
this aspect is very similar to rambo.
Comment state; Please do This or that.
Work in progress "interesting lets do it"
Comentary close "Actually we can't do that"
Commentatry deleted in case the comment as nothing to do with the document. As you could see some time ago shameless and brainless people are running freely so deleting unapropriate comments it's the best way to not have them garbeging the systeme.
Changelog "We addded this to that document"
As you follow the same ticket from comment to changelog then you can keep track who submited who realiesed and naturally if you got some neurones available you can distinguish active programers and contact them to offer them work or identify Gurus active redactor that will efficently create docs.
Well in a way that's what wave offer so maybe the ideal is to move the doc to a wave system... But i'm sure mixing a blog/RABO and a wiki is pretty doable and efficient in rebol... | Giuseppe Chillemi
16-Mar-2010 8:14:29 |
Hi Carl,
the problem with mediawiki documentation is the lack of coordination, tagging, and too wide access policy.
Take a look at the REBOL2 documentation. It links articles divided by areas,categories.
Also please remember, and sorry to remember this again, that it is 2 years since I have requested an upgrade to mediawiki and volunteered to accumulate, sort and organize, the globally available REBOL2 documentation. We are in 2010 and still there is no upgrade.
I would like to help a lot but please give me the instruments !
Giuseppe Chillemi | Paul
16-Mar-2010 10:16:06 |
Hostile Fork, I see many of the same observations that you made. | Karg
16-Mar-2010 15:58:15 |
This is the gui of the script I use to concentrate internet pages, it could be
adapted for a 2-way exchange. The net is always going
to be a very loose set of documents, to informal on its own for a manual.
rebol [
title: "Desktop Manual"
notes: {Collects from the internet pool of documents.
Administered & auto updated from Rebol HQ.
Fed by Rebol IT & community input.
End user may edit theirs & submit issues/script/examples etc.
}
]
manual-reader: layout [
size 1000x600
backdrop olive
origin 30x30
below
space 0x0
style tablet area 400x500 khaki font-size 15 bold
style chapter btn 72
page: tablet wrap {
1.1 Traversing a Series
Since a series is an ordered set of values, you can traverse it from one position to another. As an example, take a series of three colors defined by the following block:
colors: [red green blue]
There is nothing special about this block. It is a series containing three words. It has a set of values: red, green, and blue. The values are organized into a specific order: red is first, green is second, and blue is third.
The first position of the block is called its head.
--------------------------------------------------------------
Collects from the internet pool of documents.
Administered & auto updated from Rebol HQ.
Fed by Rebol IT & community input.
End user may edit theirs & submit issues, scripts, examples etc.}
return
illustrations: tablet 400x250 "Illustrations"
subjects: text-list 416x250 black khaki data [
"1.1 Traversing a Series"
"1.2 Skipping Around"
"1.3 Extracting Values"
"1.4 Extracting a Sub-series"
]
return
pad -16x0
text-scroller: scroller 16x250 [
focus page
scroll-para page text-scroller
]
return
pad 10x10
chapter "Introduction"
chapter "Operation"
chapter "Quick Tour"
chapter "Expressions"
chapter "Scripts"
chapter "Series"
chapter "Block Series"
chapter "String Series"
chapter "Functions"
chapter "Objects"
chapter "Math"
chapter "Files"
chapter "Network"
chapter "Ports"
chapter "Parsing"
chapter "Values"
chapter "Errors"
chapter "Console"
return
style click btn blue 22x22
across
return
pad 140
;clicking these buttons changes the area of interest & the button list chapters
;which in turn determine the text-list subjects
btn "Core" orange
btn "R3"
btn "Draw"
btn "Server"
btn "VID"
btn "Library"
btn "Images"
btn "Services"
pad 200
btn "Save"
btn "Quit"
]
view manual-reader | Brian Hawley
17-Mar-2010 11:20:13 |
Carl, you need to put a horizontal scroll bar on pre elements in your style sheet for this blog.
Karg, a single site can be organized enough to serve as a manual - all you have to do is be careful with permissions. It's the net as a whole that is disorganized. | Luis.
18-Mar-2010 2:31:06 |
Hiya,
What about treating the Docs as a book?
Aside from making pdf, DocBook, whatever, easier to format for printing, the approach might gel the layout design (taking onto consideration the benefits of hyperlinking).
Cheers,
Luis.
| Hostile Fork
19-Mar-2010 3:13:42 |
Paul: thanks for empathizing with my critique. Though I meant *Oscars* not *Grammys* (or if I wanted to invoke the Grammys I should have said lyrics instead of script). I live in LA close to the Kodak Theater so I really have no excuse for that error. :)
BrianH: I know you work yourself to the bone on this stuff and Carl does too. But there are so many workflow issues going on here. I know Rebol is unconventional; I sketch and draw I completely respect the importance of organic methods to discovery. By no means am I an extremist who's going to say the IBM process-oriented way is The Answer.
Still, the symptoms here show the disease. Why were esoteric parse features prioritized above a commitment to getting the try/catch behavior formalized? How can the GUI documentation be hijacked by some random guy on the internet who didn't get it and corrupted the docs? (Reverting takes *one* button push, even in silly MediaWiki.)
Scaling yourself involves trust, and Rebol seems to have a trust deficit with the world. I think it's time for the community to step up its public Google-able face.
I'm glad RebolTutorial is bringing his questions to StackOverflow, but more people should be doing Q&A there instead of AltME. The questions showcase why Rebol is cool and interesting, and it's time that newbies got hooked on the crack cocaine of programming instead of "gurus" Bogarting the whole stash behind closed doors. :P | Brian Hawley
22-Mar-2010 13:51:32 |
Fork: "Why were esoteric parse features prioritized above a commitment to getting the try/catch behavior formalized?"
We didn't know that there was a problem with try/catch behavior that required design changes until it was reported in CureCode, recently.
In comparison, we started working on proposals for adding and fixing parse features more than 5 years ago, long before R3 was even an idea, because parse is considered the most powerful feature of REBOL by most of its advanced users. And Carl decided to work on it when he did because we need parse to implement the higher-level stuff, including chat and the GUI. And at that point we had already gotten past most of the lower-level core stuff like mezzanines, extensions and modules. It was parse's turn.
We do go through rounds of bug fixing, interleaved with the design stuff. But not all bugs have been reported yet, or even recognized as being bugs in some cases. And some of the ones that have been reported aren't fully understood yet, so they have to be deferred. Or they are low priority at this stage. Or are just waiting to be dismissed.
I know it doesn't seem like it sometimes because in some ways R3 has surpassed R2, but R3 is still in alpha, and some features are still in the design phase, if that. You can't document stuff that isn't known yet by anyone. We document as we figure things out in some cases. Right now the GUI documentation (that's been collected by Carl recently, not the stuff on DocBase) is a little ahead of the implementation; that is a rare occurrence though, due to how easy it is to implement many things in REBOL once you know how.
I'll take your word for it that MediaWiki is easy to use and administer. That hasn't been my experience, but YMMV. |
Post a Comment:
You can post a comment here. Keep it on-topic.
|
