AltME: Red Docs

Messages

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.
NickA
A wiki seems like the best way to get community help collecting examples of function use.
Arnold
A wiki lowers the barrier to contribute, best would be if it were possible to import the added pearls to the 'official' docs.
Don't know if you know http://learnyousomeerlang.com/ and where it was derived from http://learnyouahaskell.com/ that kind of a site would be cool for REBOL/Red.

Henrik
Should this group not be public?
DocKimbel
No problem for making it public.
Henrik
Not sure if this is enough. Changed the title.

Gregg
On docs, in one of my dreams, I see another category along with Example and See Also: Tests. Make it easy for people to contribute tests (and expected results).
AdrianS
Agree that examples are a must have. I see way too many reference sites that just show an API along with a brief description. Even when these are very nicely presented, they leave me wanting. Seeing an APIs in action makes a huge difference to me, but of course the work of creating examples should come from the community.

james_nak
Gregg, that's a good dream and very meaning for learning. The figuring out of why something doesn't work is so powerful especially when one thinks it should.

Chris
<from #Red>
A document would be trickier as you'd need to manage line spacing, paragraph spacing, splitting paragraphs/docs over pages.
Henrik
Yes, it managed only a single page, and yes, the hard part is flow of paragraphs across pages, not generating multiple pages in itself.
Chris
(that'd be page breaks, indeed)
You'd need to be able to measure as you go...
Henrik
I'd still think that doing it in the graphics engine is simpler than in PDF. For R3, someone is probably going to do it anyway.

Last message posted 65 weeks ago.