This group is for the discussion of Red documentation. I think it's important enough, and will generate enough chat, that it deserves its own group. See #Red for previous doc chat.
Arnold
Presentation is important. Completeness is important. Explanations are important. Examples are important.
Presentation, please nothing fancy with popups on mouseover events. (besides who uses mice on tablets in future) But needed is a good design, graphical eyecandy, make it attractive.
Explanations as why Red does things in its own way. Background information, summarize discussions on the topic. etc.
Examples, like completeness says it all. Good examples say more than a 1000 words.
Pekr
I think that REBOL has good structure of reference documentation, we should copy and enhance it eventually ....
DocKimbel
Thanks Gregg, having a separate group will be helpful, it's a broad topic anyway.
Jerry
Maybe talking about this is too early, but if there is a easy way to support localization, that would be great. We hope Red's Documentation can be translated into Chinese, Japanese, ...
Gregg
I do like a lot of the REBOL docs, which took time and effort to create. Wikis are good for reference information. I agree with Arnold that good examples are important. I'll add that giving people a starting point is helpful. For example, have example scripts for different types of apps or features; CGI, pipe and filter, command line handling, etc.
I also think format fragmentation is bad. REBOL's docs are fragmented, which makes it hard to know the best place to put something. Being able to share data, or have a common doc db that can be rendered in different ways, would be great.
AdrianS
Gregg - totally agree on avoiding doc fragmentation. This is a serious consideration for newcomers who need a guiding hand to see the overall picture. It's pretty important to convey a sense of being authoritative on documentation. Another related issue is that of keeping documentation current/clean. Old, deprecated, outdated material should be deleted or at least be made a lot less visible in the community.
sqlab
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.
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..
Henrik
Carl wrote a number of examples in his blog early on. They were very helpful to me as well.
Henrik
"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.
MaxV
The best way for documentation is a wiki, where people can easily ragiter, log in and edit.
Oldes
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
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.
DocKimbel
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,...
AdrianS
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.
sqlab
If a command in RED and Rebol share the same name, but behave diferently, these differences should be clearly shown or explained
james_nak
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.
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.
Gregg
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?
DocKimbel
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.
Pekr
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
GrahamC
Many wikis have an API
Henrik
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.
Gregg
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.
Henrik
The work I did was related to publishing to mediawiki directly from REBOL. This way, some mediawiki pages could be auto-generated.
Gregg
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?
Henrik
Gabriele wrote a MakeDoc GUI a long time ago.
Gregg
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.
james_nak
Gregg?
Gregg
I can't commit to being the leader just now. I'm happy to help though.
Henrik
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.
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.
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.
DocKimbel
So, how does that option sounds to you?
AdrianS
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 http://clojuredocs.org/quickref/Clojure%20Core 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...
DocKimbel
AdrianS: Github Pages uses Markdown format, they have no support for makedoc.
DocKimbel
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.
DocKimbel
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.
DocKimbel
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.
DocKimbel
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?
AdrianS
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.
DocKimbel
Pre-generated HTML: I certainly do want that. I have already a static server, so I don't need GitHub Pages so far.
- 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.
Gregg
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.
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:
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.
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.
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.
and I hope DRAW or similar will be available for Red.
Kaj
It will
Henrik
cool :-)
Pekr
Kaj - sounds like sure thing but also news for me :-) AFAIK you and Doc were not much interested in bringing View to Red. Well, unless you mean DRAW equivalent done using different engine ...
DocKimbel
Pekr: DRAW is a dialect for 2D vector drawings.
Gregg
Ping.
DocKimbel
Funny that I even forgot that this group existed. :-) Thanks for bringing it back to life. ;-)
GregP
No real standard for MD, so I vote for a Red made parsing, similar to MakeDoc. The TOC is great. Table are so-so, the one from MakeDocPro are better.
So, in a nutshell: - github for hosting the docs (in a red/documentation repo) - markdown for the initial format (with eventually some additions) - Nim's documentation layout and style
DocKimbel
For the content itself, we need: 1) a user manual (with the same level as the Rebol/Core Manual) 2) a dictionary of the words 3) some tutorials
(1) is the biggest and most important part.
Andreas
4) a language reference
DocKimbel
You mean a language specification document?
Andreas
Yes. Everything that is not covered by the dictionary.
And stuff at a technical detail that is too much for the user manual.
One of the more important aspects: syntax. But also stuff like: binding, argument passing modes, cor e evaluation semantics.
Gregg
Language Design/Implementation Reference?
PeterWood
That's a very, very good suggestion Andreas. It won't be easy to write well. Do you think you may have a little time to help with it?
5) a dictionary of values
I always found it strange that the equivalent of the word dictionary for values was hidden away as an appendix in the Rebol user guide. I think such an important aspect of the language needs a more visible presence.
Gregg
Do you mean like a standard library reference Peter? I have notes for something like a Nutshell series book.
PeterWood
What I'm thinking of is a short explanation of each value! type.
Something like this:
A char! value represents a Unicode code point. It is a number in the range hexadecimal 00 to hexadecimal 10FFFFF.
The literal value of a char! value is of the form #"a" or #"^(0032)".
Gregg
I would call that a "reference", and could be an appendix in the core user manual.
DocKimbel
Listing all the datatypes should be part of 1).
Gregg
Yes. Working on some of that now.
DocKimbel
By the way, a preliminary work would also be to define a lexicon for the basic concepts, like talking about "variables" or not, "assigning a value to a word" vs "giving a meaning to a word in a context". We need to define a common vocabulary so that the docs look consistent regardless of who is writing.
Gregg
Yes. That will be very important.
DocKimbel
I am also wondering if a single entry point for (1) is the best option. We know from Rebol that the learning curve has at least two steps (Carl's lake analogy) the surface and the depth. The surface is very quick and simple to learn, but might be misleading or even confusing for users with a CS background. So, there's a second "advanced" step in the learning process where you usually get the "eureka" moments, once you get things like code/data duality or the nature of definitional and dynamic binding.
Gregg
I'm sure we'll want special docs for advanced users who would otherwise not find the information sprinkled in the standard user guide.
DocKimbel
So for (1), you suggest we aim at the "surface" only?
Gregg
I think (1) can, and should mention these things, but doesn't need them as complete chapters. They could be advanced chapters or appendices. But could stand alone as well.
Pekr
Wasn't there once the community effort, to bring some kind of better docs to Rebol? I remember we defined structure or something like that ...
Peter: that "value" explantion is precisely one part of what I'd put into a language reference ("(4)").
Listing of all the datatypes should of course also be a part of the user's guide ("(1)"), but on a different level. User guide is exemplary, a quick overview. The language reference should be comprehensive.
In general, I like Rebol's user guide quite a bit. What I don't like about it -- and I don't think the "user's guide" really is the place to put it -- is that it is very skimpy on almost all topics touched. It doesn't discuss the deeper technical details, the corner cases, etc.
Gregg
A quick-start guide will be good, and should be material we can extract from the official/user's guide. Or should at least be easier to write once we've done that.
PeterWood
Andreas: Yes. The definition of values should be in the language reference.
PeterWood
Perhaps I can summarise and make a short proposal:
1. We want to have good quality documentation ready for the launch of Red 1.0. (By good quality, I mean that, first and foremost , the content is accurate. Second come style and presentation.)
2. We see the need for: a. user manual b. dictionary of words c. tutorials d. language reference e. quick start guide 3. I believe that the early adopters of Red 1.0 will be either people currently using Rebol or experienced developers. The inexperienced will follow some time later.
So my proposal is to focus on the following three documents that experienced Rebollers/Developers would look for: i) Language Reference ii) Dictionay of Words iii) Quick Start Guide.
DocKimbel
Actually, I would like to have the docs (at least (1)) for the first "public alpha", so around end of March (as soon as we have good enough GUI and I/O). We'll start doing promotion/buzzing, so we need it before 1.0.
DocKimbel
Peter, Language Reference will be very technical, not practical. It won't explain you how to use Red, but describe Red's syntax (using BNF), semantic rules, notes about implementation and exhaustive list of core functions.
DocKimbel
Peter, I am hoping to attract many beginners/inexperienced users for 1.0 (or even before), and not only experienced ones. But it's difficult to predict in which category of users Red will generate the most traction.
PeterWood
So the User Guide should be the priority.
DocKimbel
I think so.
amacleod
Doc, I hope to focus on the beginners and young users myself. I taught high school science for six years and I never lost my interest in promoting programming as a tool for my students that were not necessarily interested in computers...Now wiith Red I hope to show the FUN in using computers to create things (apps/projects). My children are ages 8 and 9 and I will be using them as a test case for a book/website/curriculum that I am going to pursue.
DocKimbel
Alan, glad to hear that. I would love Red to be used for education. We would probably need to build some additional layers in provide simpler interfaces for young beginners. I think you should talk with PeterWood more. ;-)
Gregg
For all of us who want to use Red to teach, we should look at old Logo resources. There are a lot of beginner and turtle graphics examples out there, but there's also NetLogo and Brian Harvey's amazing series "Computer Science Logo Style", though that's more advanced. I even did a tiny turtle graphics interpreter in REBOL a long time ago.
Some tools and dialects are all we need. ;-)
Reichart
What has been the best resources out there for REBOL in terms of education? Learning what to do, and not do probably has value, but copying work that has already been done could save a lot of time and energy.
Andreas
> What has been the best resources out there for REBOL in terms of education?
The old mailing list ...
Gregg
Andreas +1. On docs, Carl said he didn't want the REBOL user guide copied. Nick's work, and some others', are also great resources. I hope we can leverage those in the future. The main thing there will be differences in Red that have to be accounted for. A LOT of REBOL docs will apply to Red directly as well, which is great.
And, yes, if you're thinking it would be good to document the differences as well as compatibilities between REBOL-like languages, I started some things on that a long time ago. A lot of our work now can be looking in dark corners and dusting things off. Bulk prose (the content) is the big stuff now.
Reichart
Well, "copied" is a strong word :)
I have always like the word "Homage"
Gregg
:-) I'm all for attribution on anything we can pay homage to.
DRAW Dialect Reference The old version of draw-ref.html , which I can't find online, but I have it locally.
But all these are mostly docs or references, maybe not educational for beginners to the language. I can't think of a good beginner guide for these kinds of languages, but I haven't read all, so maybe it exists.
Reichart
I'm a fan of putting a crap load of stuff on a single page, esp. "Most common used words" with lots of examples.
In general though, I go to Google, type things like "rebol parse example" and get good enough.
Arnold
I want to make a Red/System doc for assisting programming Red. The idea is to quickly look up the definitions of all the used types. Such a document will be useful for Red/System 1.0 but will be easily extended for Red/System 2.0 later.
Gregg
Not sure what you mean by "used types", but any docs are helpful.
Arnold
cell!, red-value!, red-block! red-string! etc. On the one side I would like a paper version, so an index and all. On the other side a little referential program to help you look up items fast and not searching through the sources yourself, but maybe it should use the sources.
Gregg
Ah, Red/System datatypes, got it. Using the source is often a lot of work. All clues help people contribute.
Endo
That would be helpful Arnold.
Arnold
Looking for the right datastructure to get the information in, get it presented and perhaps also have it autofilled from the sources?
; Now can select the definition of a type declaration parse _allocator [to "int-array!" copy desc thru [end-alias | empty-line] to end]
; And keep some string for all aliases in the source type-list: parse _allocator [collect any [to "alias" keep to "^/"]]
; But I want type-list: parse _allocator [collect any [to "alias" keep backto "^/"]] As with a list if the strings before the alias I can do something more useful than the end of the strings after 'alias'.
Gregg
You'll have to collect the comments first. You could set markers, but collecting them first is probably eaiser. e.g.:
The "=" prefix/suffix convention is one I use to mark parse rules and vars.
Arnold
I was creating the pieces of the puzzle that seemed easiest first. list: parse _allocator [collect any [[ahead [not [any newline] to "alias" ] keep to "alias" | newline]]] BuUt this only gets me [] So i'll try your construction now.
Very nice Gregg!
Arnold
Though I think it is much simpler just to use read/lines and work from there: _allocator: read/lines %../red-master/runtime/allocator.reds __allocator: make block! 200 foreach line _allocator [if find line "alias" [append __allocator line]]
Arnold
And the file in runtime/datatypes/structures.reds that collects the definitions will also be helpful.
Arnold
word-first-char=: complement charset {/\^^,{}"#%$@:;} ; " is incomplete? because it does not exclude digits? red>> parse "0" [word-first-char=] == true
Gregg
Good catch Arnold. I was pulling things together quickly.