World: r4wp

If there is really outdated documentation it should not made invisible, 
but marked as obsolet since when.

Maybe some programs were made with special features relying on that 
old behavior.

When I was trying to learn REBOL, the most helpful document was the 
cookbook,
http://www.rebol.net/cookbook/


Different subjects, but covers almost all the subjects, and they 
are all complete. If we do something like that and give links to 
related wiki pages about the topic of the example, it would be a 
great way to learn RED for beginners.

And the most difficult thing was the fragmented docs, we should avoid 
that..

Carl wrote a number of examples in his blog early on. They were very 
helpful to me as well.

And the most difficult thing was the fragmented docs, we should avoid 
that.

 - I suggest also later on that Red provides functions directly in 
 the interpreter to invoke any official help documents.

The best way for documentation is a wiki, where people can easily 
ragiter, log in and edit.

Arnold, you can make popups with copy and paste possibility - check 
this quick remake of the original Carl's reference page: http://rebol.desajn.net/cheatsheet.html

Here is script which I used to cerate it... note that there are not 
existing links in Carl's reference (in the GUI section). Hope Red 
will have documentation without such a silly errors.

https://github.com/Oldes/rs/commit/cb6cf1a8d2e3cb2bface3f3c13c3e071ff5e0aa1

And regarding version for tablets, I believe that it's better to 
have separate version for tablets which would better work with the 
limited screen resolution. I can imagine nice looks for that as well.. 
it just need to have nicely structured and centralised documentation 
data which can be used as a source for different looks.

I think that the best way would be to parse sources (with some unified 
structure) to get the documentation data. It should be part of Red's 
main repository.

There are many kind of docs, what I want to provide first is the 
"reference documentation", which provides an exhaustive description 
of all the language features (in a user-friendly way, not in a formal 
way) and explains "how it works". Basically the REBOL/Core manual 
(but exhaustive) + "how it works", so with some chapters on memory 
management, execution model, in depth modules/contexts/binding model,...

sqlab, I didn't say invisible, just a lot less visible. You should 
realize that outdated documentation is essentially "noise" which 
makes learning what's current more difficult. Of course there should 
always be a way to get to an old API reference. On an authoritative 
source, this should be done in a very subtle way so as to minimize 
information overload - maybe with a clear, but small link at the 
bottom of the current version docs. Non-authoritative sources can, 
of course, maintain all the old information and present it in any 
way they choose.


When it comes to advice on best approaches, optimizations, etc., 
it's very important to promote the "current" recommended way of doing 
things so that new code being written based on these docs don't lead 
to the incorporation of work-arounds for problems that have long 
since been worked out.

If a command in RED and Rebol share the same name, but behave diferently, 
these differences should be clearly shown or explained

I think I should chime in here because I am one of those people who 
are not naturally inclined toward the programming arts. I see that 
many of you realize that the docs have to reach a vast audience from 
novice to expert. That will involve using different methods of presentaton 
and detail. How would you envision the database to look like. If 
we could create something pretty complete then I think all the desired 
above could be accomplished. For what it's worth I use the following:

The rebol dictionary - to look up words and usage I can't remember, 
try to decipher some functionality I need, hopefully find examples.

The View docs - to find out how things works and to remember how 
certain words work

Everything I can find on Parse - This is one subject that is all 
over the place.

Nick's tutorial and Reboltutorial - To learn about topical items 
that one can do in rebol such as sound and animation.

Altme - Asking all of you, especially Henrik, if I can do something 
and how or when something doesn't work.
Rebol.org - To find scripts that do things I need to do

Google - OK, this is generic and possibly obvious but when I am trying 
to figure something out, it's "Rebol ..."

The above items are my  most used resources and not exclusive. Note, 
for me the R3 docs were harder to navigate, especially a few years 
ago when I was looking at the GUI stuff. To me at least they seemed 
all over the place.


So, if one were to analyze that usage, it may help to develop something 
that can accomplish those different needs.

I think that something like http://en.wikibooks.org/wiki/REBOL_Programming
is the best thing. You may organize topics, correct, edit and add 
pages

Everything I can find on Parse - This is one subject that is all 
over the place.
 - I am curious whether you read


http://en.wikibooks.org/wiki/REBOL_Programming/Language_Features/Parse

as one of the sources?

Yes Ladislav, I have and that's a good one. I guess parse requires 
some more parsing. Parse is one of the hardest parts of rebol for 
me so when I say it's all over the place it's that different people 
write different things about how to use it. I mean, it seems like 
someone could write an entire book on it for guys like me. One place 
I continue to go to is Brett's http://www.codeconscious.com/rebol/parse-tutorial.html
but when it comes to dialects

That all said, perhaps this leads us to documentation that is very 
tutorially-oriented. Thank you for your response, Ladisalv.

Doc, for implementation details, you and a few others who know will 
have to provide the basic information. If there is cleanup and wordsmithing 
to be done, as long as others can edit it easily, I would leave that 
to someone else. Write the best doc you can, of course, but don't 
worry if it's not perfect. Your time should be spent doing things 
nobody else can do as well, using what you know, and what you know 
is planned.


For friendly user reference, do you have a style of docs you want 
to mimic, or an idea of how you want the doc data managed? e.g., 
do you want to use a wiki, so that infrastructure is all there?

I think a wiki like Wikibooks could be a good start, but I would 
like to use makedoc format. I know that the R3 wiki has been adapted 
to accept makedoc format as input, how could we do the same for Wikibooks? 
Is it possible to export all wikibook content to a parse-able format? 
I don't want to be trapped in a given tool, I want to be free to 
retarget docs to whatever format/tool we find appropriate in the 
future.


If wikibooks is not the best tool for the job, we might want to install 
a copy of R3 wiki on another server.


The only issue I have with wikis is that we need someone in charge 
there, reviewing every single change and filtering them when needed. 
Without someone fulfilling that role, it will quickly become a big 
mess.

I think that e.g. Mikrotik used the same wiki Carl choosed for R3, 
and they made it a bit prettier. I would find such docs good enough 
- http://wiki.mikrotik.com/wiki/Main_Page

Many wikis have an API

About wikis, I would probably prefer that the document structure 
is fixed, and then each page can be a wiki. We had problems early 
on with the R3 GUI documentation that someone changed it.

I'm with Doc and Henrik. Wikis are great for letting people contribute, 
but they never have the same feel, IMO, as a polished document. A 
main reason for that is the primary way wikis work: many voices. 
I think we need a wiki, or something that makes it just as easy to 
contribute, but we also need a more formal structure and control 
for some things, as Henrik says.


Henrik did some great work on a MediaWiki interface for R3 DocBase. 
I don't remember the details of how it worked, but I still have it 
here, so we could look at that as a starting point.

I don't know if MediaWiki has per-user page control, but I think 
wikidot does.

The work I did was related to publishing to mediawiki directly from 
REBOL. This way, some mediawiki pages could be auto-generated.

Someone also wrote a makedoc GUI, didn't they? Are there tools like 
that for managing a doc base? I also agree with some earlier comments 
about some commercial sites having very good docs. How do they do 
it?

Gabriele wrote a MakeDoc GUI a long time ago.

Looks like Gigaspaces uses a wiki, and Confluence is in their footer.

Ah yes, thanks Henrik.

To amend my earlier statements, a wiki as a platform is not the problem. 
The problem is putting up a wiki and expecting great documentation 
to appear, without someone to set up a structure, design, and maintain 
it. You need a leader.

Gregg?

I can't commit to being the leader just now. I'm happy to help though.

I would write the structure as a dialect and sub-page generators 
from that. Each page would be a plain text file or a set of files 
which can be separately edited through a simple web interface.

I'll try to get back later, to pull other doc links from the #Red 
group. In the meantime, here is one:

http://wiki.gigaspaces.com/wiki/display/XAP9/XAP+9.0+Documentation+Home


I like the upper right link categories: API docs, Forum, Blog, White 
Papers.

Find something to emulate, whatever it may be. Learn from others 
who have done this before.

http://www.wikidot.com/doc:api-methods

https://www.dokuwiki.org/dokuwiki

http://clojuredocs.org/
http://api.clojuredocs.org/

http://www.rebol.com/docs/reference.html
http://w3schools.com

This is an interesting approach: http://clojuredocs.org/quickref/ClojureCore

the Scala doc site seems pretty decent, as well: http://docs.scala-lang.org

Oldes: nice mashup!

We might have another good alternative option to the wiki (maybe 
easier and more flexible): use a github repo for all the    documentation 
pages in makedoc format, and have external export batch script to 
export them in HTML, PDF or whatever format.

I would be able to write most of the reference documentation, but 
would probably let the dictionnary be written by the community. The 
githun repo would allow for everyone to contribute while being filtered 
by one or several managers.

I would like to copy this extjs template component for documentation, 
with content in JSON format:
- http://docs.sencha.com/ext-js/4-1/#!/guide
- http://docs.sencha.com/ext-js/4-1/#!/api

I guess it should be search-engines friendly.

BTW, this extjs template handles user comments also....Not sure we 
would need it as it is possible to add comments to github source 
code.

So storing the docs in source format in a DVCS repo would allow us 
to generate static web pages for the docs, avoiding   (potentially 
painful) tweaking and maintainance of a PHP-based wiki engine.

So, how does that option sounds to you?

Are you also thinking of serving the docs site(s) from github pages 
as well?

http://pages.github.com

I like the sencha guide page OK, but I like http://clojuredocs.org/quickref/ClojureCore 
better than the sencha API page. It seems like a better fit for Red/REBOL 
to me. Guess I'll really have to learn git now. 


Now, where is that new version of altme that uses git for file sharing 
and just hides all the details...

AdrianS: Github Pages uses Markdown format, they have no support 
for makedoc.