1. Euphoria Documentation Project
- Posted by simulat <simulat at INTERGATE.BC.CA>
Mar 28, 2000
-
Last edited Mar 29, 2000
Hi
Some initial thoughts about a Euphoria Documentation Project:
Here's one idea that might work.
A programmer discovers a problem in the docs - something is missing or
unclear. They post their observation. Someone who is knowledgeable about the
issue writes an article. The article is posted for review and comment. After
the review and correction (if needed) the article gets incorporated into the
final Manual, FAQ, or HowTo.
For those who are looking for projects, there are a bunch of little software
entities that could be made to support this effort. We could have a set of
programs that are forms into which documentation requests and the
documentation itself could be typed. This would greatly simplify the use of
the tags that would then facilitate the rest of the document creation
process. We could have other programs that translate the tagged document
into various format like rich-text and html, and whatever the format used
for the compiled html of Adam's new Manual.
Part of our strategy should be to keep each task very small, and by
automation to eliminate as much of the drudgery as possible. It might be a
good idea to use the way data is transmitted on the net as a model for how
we handle the tasks. The projects should be broken down into small,
semi-autonomous little chunks, that are labeled in such a way that they
automatically assemble themselves into the finished document without there
having to be an overall author or editor.
Anyone have any thoughts on this?
Bye
Martin
2. Re: Euphoria Documentation Project
- Posted by Greg Phillips <i.shoot at REDNECKS.COM>
Mar 28, 2000
-
Last edited Mar 29, 2000
----- Original Message -----
From: simulat <simulat at INTERGATE.BC.CA>
To: <EUPHORIA at LISTSERV.MUOHIO.EDU>
Sent: Tuesday, March 28, 2000 10:47 PM
Subject: Euphoria Documentation Project
> Hi
>
> Some initial thoughts about a Euphoria Documentation Project:
....
> Anyone have any thoughts on this?
>
I really, really like the idea of any open, coordinated documentation
project. The part I like about the Linux Documentation Project, is that
it's open to articles on everything from how to use "ls" to it's fullest, to
how to write directly to video memory in C!
It shouldn't be restricted to just areas of the existing documentation that
need updating or refining, but rather a central location for any
documentaion of libraries, articles, tutorials, and other written works.
Anyways, just my 2 cents. Or rather, my 1.38 cents, Canadian funds =)
Greg
3. Re: Euphoria Documentation Project
I think the most important thing is to be centralized by someone. You're
ready to be the coordinator?
Another point about various formats. The LDP project uses only one format,
SGML, and tools to translate into txt, html, dvi and ps files. probably most
people won't want to go into that, but the coordinator could.
btw, it's a really good project.
Riwal
> -----Original Message-----
> From: simulat [SMTP:simulat at INTERGATE.BC.CA]
> Sent: Wednesday, March 29, 2000 8:47 AM
> To: EUPHORIA at LISTSERV.MUOHIO.EDU
> Subject: Euphoria Documentation Project
>
> Hi
>
> Some initial thoughts about a Euphoria Documentation Project:
>
> Here's one idea that might work.
>
> A programmer discovers a problem in the docs - something is missing or
> unclear. They post their observation. Someone who is knowledgeable about
> the
> issue writes an article. The article is posted for review and comment.
> After
> the review and correction (if needed) the article gets incorporated into
> the
> final Manual, FAQ, or HowTo.
>
> For those who are looking for projects, there are a bunch of little
> software
> entities that could be made to support this effort. We could have a set of
> programs that are forms into which documentation requests and the
> documentation itself could be typed. This would greatly simplify the use
> of
> the tags that would then facilitate the rest of the document creation
> process. We could have other programs that translate the tagged document
> into various format like rich-text and html, and whatever the format used
> for the compiled html of Adam's new Manual.
>
> Part of our strategy should be to keep each task very small, and by
> automation to eliminate as much of the drudgery as possible. It might be a
> good idea to use the way data is transmitted on the net as a model for how
> we handle the tasks. The projects should be broken down into small,
> semi-autonomous little chunks, that are labeled in such a way that they
> automatically assemble themselves into the finished document without there
> having to be an overall author or editor.
>
> Anyone have any thoughts on this?
>
> Bye
> Martin
4. Re: Euphoria Documentation Project
Martin,
I like the idea of some more documentation for Euphoria very much, but I
have to agree with John McAdam that your question/response protocols are too
off-putting. I can understand your desire to reduce the labor intensive
nature of the project, but I think his idea of a question form to fill out
on a web site is much better, although I wouldn't want it restricted to just
web ring members.
As an alternative, when I first noticed the unfortunate lack of a Euphoria
FAQ, my thought was that everyone who asks questions on the list could
"re-pay" the general helpfulness of the list members by contributing their
questions & received answers to a FAQ, thus distributing the load for
creating it. I assume that most who ask questions probably *save* the
answer(s) they receive, for future reference, and could relatively easily
sort through them on a monthly basis & send their questions & the answers(s)
to whoever might be maintaining the FAQ, which could then be copied to
various member's web sites. At worst case, list members could sort through
the list archives for some of their own questions, & pick good answers to
send in for the FAQ.
Dan Moyer
-----Original Message-----
From: simulat <simulat at INTERGATE.BC.CA>
>Hi
>
>Some initial thoughts about a Euphoria Documentation Project:
>
>Here's one idea that might work.
>
>A programmer discovers a problem in the docs - something is missing or
>unclear. They post their observation. Someone who is knowledgeable about
the
>issue writes an article. The article is posted for review and comment.
After
>the review and correction (if needed) the article gets incorporated into
the
>final Manual, FAQ, or HowTo.
>
>For those who are looking for projects, there are a bunch of little
software
>entities that could be made to support this effort. We could have a set of
>programs that are forms into which documentation requests and the
>documentation itself could be typed. This would greatly simplify the use of
>the tags that would then facilitate the rest of the document creation
>process. We could have other programs that translate the tagged document
>into various format like rich-text and html, and whatever the format used
>for the compiled html of Adam's new Manual.
>
>Part of our strategy should be to keep each task very small, and by
>automation to eliminate as much of the drudgery as possible. It might be a
>good idea to use the way data is transmitted on the net as a model for how
>we handle the tasks. The projects should be broken down into small,
>semi-autonomous little chunks, that are labeled in such a way that they
>automatically assemble themselves into the finished document without there
>having to be an overall author or editor.
>
>Anyone have any thoughts on this?
>
>Bye
>Martin
and John McAdam responded to some zipped up suggested question/answer
protocols contained in another post:
<The proposed model looks pretty difficult for us simpletons.
If this was a web page where you could fill in some form
of the kind you suggest it might be viable. The web page
could be clickable from members of the euphoria web ring.
Then another form for answers... Hmmm...This is a lot of
extra work for us. Keep thinking.>
5. Re: Euphoria Documentation Project
- Posted by simulat <simulat at INTERGATE.BC.CA>
Apr 08, 2000
-
Last edited Apr 09, 2000
Yup - a good idea - a website. But I was thinking of a website as more of a
place to put the FAQ.
The problem with a website for data entry is this: How do you get the
request from the website to the list so that people can respond? So, as I
see it, the problem with websites a this stage is that they require the
responders to go to the site to look for problems to solve - my guess is
that they won't. So I seek a way to handle the whole thing as messages on
the list - people post questions now, people respond. What I hope to do is
take advantage of that and just automate it a bit so that the questions and
answers can be gathered and compiled without a lot of intervention.
Another thing that I want to accomplish is to get a format that'll let me
mine the list's past postings to get a bunch of material to start the FAQ
off.
I'm still working on the problem of how to make the forms clear, and from
the feedback I can see that I've a ways to go yet. Hopefully, I can get to a
readable enough form that people can give me some feedback about whether
they think I'm gathering the right information.
But really - text substitution in an ascii file is too hard for people to
handle? I actually thought it would work pretty well - people could just
keep a copy of the request form on their harddrive, and fill it out and send
it in whenever they had a question. Similarly, people could keep a copy of
the response form and when they have an answer to offer they would just fill
out that form and send it in. By using the forms, then I. or someone can
just set up a filter that'll dump the info into database. That seems quite a
bit easier than a web form to me.
Bye
Martin
----- Original Message -----
From: Dan B Moyer <DANMOYER at PRODIGY.NET>
To: <EUPHORIA at LISTSERV.MUOHIO.EDU>
Sent: Saturday, April 08, 2000 7:33 PM
Subject: Re: Euphoria Documentation Project
> Martin,
>
> I like the idea of some more documentation for Euphoria very much, but I
> have to agree with John McAdam that your question/response protocols are
too
> off-putting. I can understand your desire to reduce the labor intensive
> nature of the project, but I think his idea of a question form to fill out
> on a web site is much better, although I wouldn't want it restricted to
just
> web ring members.
>
> As an alternative, when I first noticed the unfortunate lack of a Euphoria
> FAQ, my thought was that everyone who asks questions on the list could
> "re-pay" the general helpfulness of the list members by contributing their
> questions & received answers to a FAQ, thus distributing the load for
> creating it. I assume that most who ask questions probably *save* the
> answer(s) they receive, for future reference, and could relatively easily
> sort through them on a monthly basis & send their questions & the
answers(s)
> to whoever might be maintaining the FAQ, which could then be copied to
> various member's web sites. At worst case, list members could sort
through
> the list archives for some of their own questions, & pick good answers to
> send in for the FAQ.
>
> Dan Moyer
> and John McAdam responded to some zipped up suggested question/answer
> protocols contained in another post:
>
> <The proposed model looks pretty difficult for us simpletons.
> If this was a web page where you could fill in some form
> of the kind you suggest it might be viable. The web page
> could be clickable from members of the euphoria web ring.
> Then another form for answers... Hmmm...This is a lot of
> extra work for us. Keep thinking.>
>
