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.