Tutorials

[Joe Armstrong (TN/EAB)]

Martin,
 
I don't like the idea of you editing my tutorials - but I do like the
idea of you defining and maintaining
the guidelines and tools for producing tutorials.
 
If you edit my tutorials you could introduce errors, and use formatting
that I think detracts from the text,
and I just don't want this to happen.
 
I'm sorry, but I just do not want other people editing my texts and
republishing them.
 
I do not like the model "anybody can edit this text" but I do like the
model "only authors
can edit the text" and anybody can comment.
 
<< the system I and Uff are making will be exactly like this - only
authors can edit text,
non-authors will be able to add questions to the text (these will be
formatted as a single non-obtrusive
question mark in the text flow) - when you mouse hover over the question
mark you will get
see the question - anybody can answer, the answer will go into the hover
box) >>
 
If you provide a standard and tell people "follow this standard" then I
will happily comply - *if I like the standard*
 
The original trap-exit site how to's which used the gentoo document
dtd's were a great step in the right direction.
 
IMHO - is is critical that the documentation format is fixed, frozen and
well-defined - so that tools can be
written to automatically digest and reprocess the inputs. Vanilla HTML
etc is just not good enough.
I think the only possible alternative is properly validated XML (we
could have used SGML, but maintaining the
tool chains is becoming bothersome) with an appropriate DTD.  
 
The next point concerns the stability of the site - the next time we
move the documentation we want to
move to a URL that stays fixed for a long time - previous attempts to do
this have always failed.
 
To solve both these problems I would like to suggest the following:
 
    1. We store the tutorials as static content (ie no mysql, php, yaws
... in the background :)
        with no wiki's etc to allow editing (you could point to an
off-site wiki for discussions etc)
 
    2. We have a single master site and a number of mirrors for the
entire site
        - so we need volunteers for mirrors, and a volunteer for the
master site
 
   3. We use the gentoo documentation tool chain
       http://www.gentoo.org/proj/en/gdp/doc/doc-tipsntricks.xml
 
In addition we need a website and some administration around all of this
- so I guess a version (-1) 
is just a simple list of pointers to tutorials.
 
Here are some tutorials I have written
 
http://www.sics.se/~joe/tutorials/robust_server/robust_server.html
http://www.sics.se/~joe/tutorials/web_server/web_server.html
http://www.sics.se/~joe/tutorials/client_server/client_server.html
<http://www.sics.se/~joe/tutorials/client_server/client_server.html>  
http://www.sics.se/~joe/tutorials/wiki/wiki.html
http://www.erlang.org/faq/parsing.html
http://www.erlang.org/examples/examples-2.0.html
http://www.erlang.org/examples/win95demo/win95demo.html
 
Now I will happily convert these to the gentoo format (If this is what
we decide to do)
And I will happily allow you to reference these. But I do not wish you
to reformat these in any
way without my explicit permission.
 
/Joe
 


________________________________

	From: owner-erlang-questions@REDACTED
[mailto:owner-erlang-questions@REDACTED] On Behalf Of Logan, Martin
	Sent: den 17 augusti 2006 19:29
	To: erlang-questions@REDACTED
	Subject: RE: Tutorials
	
	

	I have gotten a few responses with some good ideas.  I think
that this can be a community effort and still get done quickly and
completely.  Here are the steps I think would be best for getting this
accomplished - fast

	 

	1.	Send to the list, this thread, any and all links to
tutorials that exist 
	2.	When the posting slows down I will extract a list of
links from the thread and someone from trap exit or the erlang wiki can
take the time to put them on the website. 
	3.	Start a new thread on suggestions, and hopefully
examples, for the layout and structure of the tutorials - I like the
format from trap exit and I also like the erlang docs site. 
	4.	Use the wiki to allow people to sign up for tutorials to
format - I will volunteer right now to do many of them. 
	5.	Post the final copies on erlang websites all over the
net, but have a versioned master copy somewhere for easy updating.   

	 

	Thoughts, comments...?

	 

	Cheers,

	Martin

	 

	
________________________________


	From: owner-erlang-questions@REDACTED
[mailto:owner-erlang-questions@REDACTED] On Behalf Of Logan, Martin
	Sent: Thursday, August 17, 2006 9:29 AM
	To: erlang-questions@REDACTED
	Subject: Tutorials

	 

	All, I would like to collect and format all the existing
tutorials for erlang/otp.  I would like anyone that has written a
tutorial about anything to please forward it to me or the list.  I am
going to endeavor to format them, perhaps copy the style of the erlang
docs, but I am not positive, and then make them available.  I will
credit the authors of course.  I think it would be helpful for new
people coming to the language to have a nice compendium of tutorials.
You can forward me the tutorials in any form and I will do the work to
get them all formatted nicely and then email the collection, as a pdf,
back out as well as make it available on the web.  

	 

	Cheers,

	Martin  

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20060821/13ffc09f/attachment.htm>