Re: LuaForge Documentation (call for writers)

[Gerhard Sittig <Gerhard.Sittig@...>]

On Tue, Mar 27, 2007 at 19:17 -0300, Andre Carregal wrote:
> 
> As some of you have already noticed and rightfully complained, LuaForge
> currently lacks documentation even for the simplest tasks. Examples of the
> missing pieces would be a FAQ, details on using CVS, managing projects,
> managing sites etc.
> 
> As LuaForge gets more users and projects, this issue is just getting bigger
> and it would be nice to offer some introduction text for new users and
> project managers.
> 
> [ ... ]
> 
> The problem is that both me and Paulo are not currently able to write such
> documentation so I'm checking with the list if someone could do that on the
> Lua Wiki. Surely both of us would be helping with the details.

I understand that this call is somewhat related to my filing the support
request? :)  And the fact that these requests have been the same over
the past years. :>


Unfortunately this thread immediately was hijacked into a "please
provide SVN" thing, which was not the most pressing problem I can see
here.  Although having SVN would be nice, there already is CVS.  But not
being able to access a project at all _is_ a problem.

So I went ahead and started a "LuaForgeNewProject" page last night in
the lua-users.org wiki.  Currently there is a rough outline of what might
need to be described there, but details are missing.  There already have
been followups, too, questioning whether this document belongs to the
wiki or not.  The current line seems to be to develop the page in the
wiki and to certainly move it to LuaForge when it's useful (I understand
that this was the idea right from the start).

Unfortunately any further submission of mine keeps getting rejected by
the wiki.  The completely unhelpful message is "Sorry, your change was
not accepted." (yes, this is a full citation of the complete error page,
isn't that nice?).  The preview works, but saving the change does not.
Setting a user name in the preferences, or reloading, or submitting a
different change -- none of that works.  


To cut it short:  There really _is_ a lack of documentation at the
moment.  This is not just about guiding those people who "want a tour"
what they could do, it's as well about those who _do_ know where they
would want to go but just _cannot_ because of a tiny little fragment of
information missing.  It keeps project owners from accessing their own
projects, and it keeps users from seeing anything of the project and
contributors from participating.  The LuaForge.net admins keep getting
support requests about the very same problem which they could solve or
avoid by such a helpful introductory document instead of spending their
time answering the same questions again and again.

There is the question how and where to develop the documentation.  The
lua-users.org wiki was suggested, but has its issues.  The LuaForge
Support SCM is probably not the place (would either need tunneling all
changes through the admin or would need a lot of committers while the
admins still need to moderate the changes), the forum may not be
appropriate for writing / collecting a document.

What's most important is to actually collect the information which is
needed but currently missing.  And contributors who have mastered a step
and know how to do something as well as those who still have the problem
and can tell what would help them.  Doing the markup once the content is
there is less urgent.


virtually yours
Gerhard Sittig
-- 
     If you don't understand or are scared by any of the above
             ask your parents or an adult to help you.