World: r4wp

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.

Gregg: the Red dictionary could be displayed in different ways, the 
treeview (unfolded like for clojuredocs or navigatable like in the 
Sensha demo) is one option, another is displaying it like REBOL's 
one: 

http://www.rebol.com/docs/dictionary.html


Anyway, the dictionary is a not the "reference documentation" (think 
REBOL/Core manual) which should be the first focus.

I'm also adding other features we should have for Red docs:

- search field: a true local search engine, not a wrapper on Google 
search.

- versioning: ability for users to consult any previous version of 
the docs.
- a simple way to track changes in the docs.

For now, I would just link the docs from red-lang.org and host them 
on static.red-lang.org which points to my own server.


In a few months, when bootstrapped Red will be complete, I would 
like to move all to a new, more appealing web site. I might use a 
github repo for managing the static parts of the web site. I would 
also move the blog to WordPress or anything else than Blogger.

About Git, it is not that complicated, you just need to learn a few 
(2-3) usage patterns to be able to install/update your local repo 
and submit a change. Maybe someone could provide a simple Red-repo-oriented 
tutorial using TortoiseGit and command-lines for those basic usage 
patterns?

GitHub Pages also serves up static html/css/js. Still, if you couldn't 
use any server-side scripting, you'd need to pre-generate the html 
and I guess you wouldn't want to do that.

Pre-generated HTML: I certainly do want that. I have already a static 
server, so I don't need GitHub Pages so far.

What I like about http://clojuredocs.org/quickref/ClojureCore, 
compared to the rebol dict page and senha API page, is:


- No need to expand or collapse the TOC on the left. You can see 
two top-level headings. 

- Single scrolling page you can scan. And I do like the visible scrolling 
in this case.

- Summary doc string visible for each item. Again, good for scanning.

- Having the number of examples listed is nice, and shows what needs 
examples.

- It's a clean, effective layout to my eye, providing useful detail 
before drilling down.

Having the doc string there has the benefit of letting you use Find 
on a web page to help locate what you want by purpose rather than 
name. Having an a.k.a. (Also Known As) annotation could help too. 
I did this for myself when starting with REBOL, noting what equivalent 
funcs were in the environment I was coming from.

While I can't commit to being the doc lead, if someone creates templates 
for output formats, and we have data in REBOL format to populate 
them with, I will commit, happily, to building doc generation tools.

Just looked at http://clojuredocs.org/clojure_core, and it is *not* 
a useful layout IMO.

Gregg: documenting the API (the Red words) is the easy part. The 
content could (should?) be extracted from the docstrings in boot.red 
(I haven't add any so far, contributions are welcome).


The level of info displayed by the clojuredocs quickref is fine to 
me, I have used similar approach in the past for documenting the 
RSP API: 

http://cheyenne-server.org/docs/rsp-api.html

Oldes, really nice popups with copy paste. Much better. Hard to believe 
you need a cheatsheet off-course ;-)

So the Red docs are not makedoc(2) specific. You only want to be 
sure that they are in a format that can be handled using scripts 
like makedoc123 and generate all kinds of documenttypes, like webpages, 
pdf, (epub?) etc. If I understand correct.

Makedoc would be the source format for the docs, the users would 
consume it in one of the exported formats available.

Looking more at sencha/ext-js and closuredocs, I like aspects of 
both. Sencha has some very nice detail pages, and closuredocs has 
a clean feel, with easy ways to add examples, see also entries, and 
comments.

Now I have to re-learn fetching the upstream master to my fork...

Gregg: unless you actually want to push changes to your fork on Github, 
there's usually no need to maintain a "fork" on Github.

If you meant how to get the latest changes from Nenad's master into 
your local repository, that could/should be as easy as `git pull`.

(Depending on where you originally "cloned" from.)