AltME: Red Docs

Messages

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.
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.
MaxV
I think that something like http://en.wikibooks.org/wiki/REBOL_Programming is the best thing. You may organize topics, correct, edit and add pages
Ladislav
"Everything I can find on Parse - This is one subject that is all over the place." - I am curious whether you read
http://en.wikibooks.org/wiki/REBOL_Programming/Language_Features/Parse
as one of the sources?
james_nak
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

Last message posted 65 weeks ago.