AltME: Red Docs

Messages

Gregg
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.
Endo
When I was trying to learn REBOL, the most helpful document was the cookbook,
http://www.rebol.net/cookbook/
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
Oldes
Here is script which I used to cerate it... note that there are not existing links in Carl's reference (in the GUI section). Hope Red will have documentation without such a silly errors.
https://github.com/Oldes/rs/commit/cb6cf1a8d2e3cb2bface3f3c13c3e071ff5e0aa1
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.

Last message posted 403 weeks ago.