AltME: Red Docs


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:
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?
I like the sencha guide page OK, but I like 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:
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 and host them on 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, 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, 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 (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:
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.

Last message posted 103 weeks ago.