I'm going to make a programming tutorial, I need your opinion | Hacker News Reader

I'm going to make a programming tutorial, I need your opinion

2 pointsmarianoguerra4 comments

Hi, I need to write some kind of tutorial/documentation for a programming language I created (http://marianoguerra.com.ar/efene/) and I would like to know which kind of books or tutorials are the best for you.<p>for example I like these 3:<p><pre><code> * http://learnyousomeerlang.com/ * http://learnyouahaskell.com/ * http://diveintopython.org/ </code></pre> this tutorial will be the first documentation for the language, so I don't know if doing it informal would be good or not.<p>Also, I would like to hear some kind of examples that would be interesting to use, I don't want to write a factorial or some abstract example, but something that is usable.<p>The target of the tutorial is for people that come from mainstream languages (C/C++/C#/Java/Javascript/Python) and would like to learn a functional programming language, or want to play with erlang but don't like the syntax.<p>advices?

> The target of the tutorial is for people that come from mainstream languages (C/C++/C#/Java/Javascript/Python) and would like to learn a functional programming language, or want to play with erlang but don't like the syntax

Recently, I saw a tutorial somewhere (maybe Scheme) where there were different pages for people coming from different languages. That's a lot of effort, but its a thought. So someone from Python can see some typical python sample, and how to do it in your language. Same for other languages.

Typically, we wish to see how to do something in a new language that we used to do in the earlier one. Going from Java to Ruby, I was always looking for this till I actually came across a blog post meant for Java programmers moving to Ruby. (For example, how to do the main() in Ruby).

I have a slightly tangential question. I am writing a tutorial for a [library](http://rbcurse.rubyforge.org/tut0.html). I'd like the tutorial to have a proper format with Previous and Next links on top and bottom, a TOC, perhaps Index.

Is there some kind of simple tool that generates these ? Or do people write out the whole thing in HTML.

I'm using sphinx an it's really awesome, you can see how it looks (I tweaked it a little)

http://marianoguerra.com.ar/efene/tutorial/

I believe some LaTeX to HTML converters do this. You also get the added benefit of being able to provide a PDF version, or publishing it as a book, with minimal extra effort.

Reply on news.ycombinator.com