AltME: Red Docs

Messages

DocKimbel
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
Arnold
Oldes, really nice popups with copy paste. Much better. Hard to believe you need a cheatsheet off-course ;-)
Arnold
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.
DocKimbel
Makedoc would be the source format for the docs, the users would consume it in one of the exported formats available.
Gregg
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.
Gregg
Now I have to re-learn fetching the upstream master to my fork...
Andreas
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.)
Gregg
I'm trying the github Windows client, which should sync, but only have my fork in it right now. I thought the target workflow (in general) was to fork, push to that, then submit a pull request. My problem is spending little time on it, then letting it sit idle while it leaks out of my brain.
Andreas
Yeah, fork + push to fork + pull request is one typical contribution workflow.
However, if you just want to follow along with the updates, then you don't need your own fork and can just sync a local clone of Nenad's repository.

Gregg
But I should fork+push+pull-req if I want to, say, add comments to %boot.red.
Andreas
Yep.
Pekr
I don't want red docs, I want black&white ones :-)
Pekr
My take is as follows:
- I like REBOL Word Browser - it contains even examples, is then easy to produce runnable examples (Easy VID), allows comments
- REBOL reference manual is good enough. I can't see any advantages with Clojure etc. - imo no need to copy anyone - just make a structures, which allow you to register related functionalities, add comments, examples
- I agree with Doc, that first Doc which should appear is some guide, which leads you via introduction to language, its main ideas and concepts, etc.
- word reference shoudl be auto generated imo .....
Gregg
I thought of the Word Browser as well Petr, and agree with your comments. On ClojureDocs, though, my thought is that the main structure is the auto-generated part, and the comments and examples are added to that.
Pekr
That might work. I wonder about some functionality removal - what happens with related docs then? Is there going to be any versioning? Some good notes might be lost that way ...
Gregg
Marking things as obsolete, and/or moving them to an archive area makes sense.

NickA
I don't have a preference for format, but I think some way to cross reference related functions is critically important.  Reference documentation is essential, with extensive examples, then with that in place, cross reference links are a natural way to explore language functions.  It's natural to think "How do I..." when learning, and exploring related functionality is an intuitive way to learn.  Once function reference, examples and cross reference links are done, then a cookbook is a natural step, and then various tutorials aimed at different levels and interests.
The online REBOL dictionary and the Word Browser are both effective formats for cross referencing.  Something like Carl's REBOL manual is essential to get things started.

Last message posted 65 weeks ago.