[Pipmak-Users] Re: Basic Mac help

[Christian W. <cwa...@gm...>]

Hi Liam

Urs has already said a lot of what I'd have answered, but let me (as 
Pipmak's author) elaborate on some points.

First of all, thanks for bringing up the topic. I sometimes worry that 
there might be a lot of people in a similar situation to yours, 
potential Pipmak users, but who are too busy or afraid or whatever to 
ask questions (that I would happily answer) and so are turned away from 
Pipmak.

Let me explain why the state of documentation for Pipmak is what it is. 
The reason I did not start with writing a tutorial (or other entry-level 
documentation) is that I'm not too fond of tutorials myself. I usually 
find that I learn faster by examining examples, doing my own 
experiments, and looking things up in reference documentation. That's 
why I provide examples (the demo project that contains examples of how 
to use any of Pipmak's features) and reference documentation 
(Reference.pdf, which is still incomplete, but should be quite usable by 
now). I realize that this style of documentation, essentially tailored 
to myself, may not be the right thing, or not sufficient, for other 
people. Therefore I would be very happy to have some complementary 
entry-level documentation, such as a simple tutorial, for Pipmak. I have 
not written such documentation myself for the following reasons:

1. There is still a lot to do in Pipmak code-wise. Doing this requires 
programming skills, and having in-depth knowledge of Pipmak's code makes 
it easier. Since I am the one who currently has more of that knowledge 
than anyone else, that looks like a job for me (but contributions are 
still welcome, of course). Entry-level documentation, on the other hand, 
can just as well (or maybe even better) be written by a contributor 
without programming skills (but perhaps better writing and teaching 
skills than mine). So, it seems to me that time is better spent with me 
programming and a contributor writing documentation than me writing 
documentation and the contributor doing nothing.

2. If I were to write entry-level documentation, it would inevitably end 
up in the same style as the reference (and the comments in the demo 
project). That means that if you don't understand some concept in the 
reference, you possibly also wouldn't understand it in a tutorial 
written by me. In addition, I may neglect to properly explain things 
that (subconsciously) seem obvious to me as a programmer and as someone 
perfectly familiar with Pipmak. An outsider, on the other hand, seeing 
things with fresh eyes, may be able to explain them in different ways 
and anticipate beginners' problems better.

In short, I heartily encourage anyone who would like to help improve 
Pipmak to consider writing such documentation. Maybe you? Don't forget 
that I'm here to answer your questions, you don't have to be an expert. 
I'm willing to guide you as much as necessary, this still is less work 
for me than writing a full tutorial.


> But as it is, for someone without a basic understanding of how to get 
> started, one can't do anything. And none of the Lua sites (that I can 
> find anyway) give a basic overview of any of this. All of them are aimed 
> at people who are already programmers and are new to Lua only.

As Urs already said, you don't need to know anything about Lua for 
simple projects. So I guess the problem for me to solve is how to better 
make people aware of that.

> What is needed is a basic step by step process that introduces first the 
> new paradigm of writing programs on a mac and goes from there. ie. Does 
> one have to install Lua for Mac on your machine first? If so how is that 
> done? How does one see/work on/ "compile" (hard as it may seem to 
> understand, to many many people, compiling is not a concept many people 
> have any idea of) files? What is the "Console" program and how does it 
> work - again there is no reference material on any of this anywhere I 
> can find.

It's not necessary to install anything, it's not necessary to compile 
anything, and it's not necessary to use the console. Is there anything 
in Pipmak's documentation or on the web site that is giving you the 
impression you'd have to do any of these things? The question is meant 
to sound friendly, not arrogant - I'm genuinely interested, because if 
there is, that's something I need to fix.

> As it is, all the documentation assumes a level of programming 
> understanding beyond what I would assume many of the possible users of 
> Pipmak have.

That may be true, but it's not meant to. I'd like to change that, but I 
need help. Do you think an additional piece of entry-level documentation 
would alleviate the problem, or are there also things that need to be 
explained more throroughly in the reference?

It's true that authoring a Pipmak project currently means writing text 
files, and not dragging stuff around with your mouse, but don't let that 
discourage you. It need not have much to do with programming if you 
don't want to. In addition, graphical editing features are planned (some 
fragments are even in place already, but as they aren't really useful 
yet, they're hidden by default).

> I only share this as I have talked to many people who might use Pipmak 
> and become loyal users/developers/community members, if only they could 
> find a little help with understanding what is basically a new paradigm. 
> In general, most such people come from other disciplines, graphic 
> experts/3d modellers, interactive fiction writers, etc.

It would be very exciting to have those people. Although I'm hesitant to 
encourage too much evangelism at this point because Pipmak is really not 
suited yet for more ambitious projects (the most important missing 
features are sound and movies), people who are willing to actively 
participate and help each other out are very welcome.

I think the main problem at this time is that Pipmak is still 
essentially a one-man project, which means that it progresses very 
slowly, both on the feature front and the support/documentation front.

Thanks for your thoughts!

  -Christian