Docs and the wiki

classic Classic list List threaded Threaded
9 messages Options
Reply | Threaded
Open this post in threaded view
|

Docs and the wiki

Daniel Wallin-3
First, let me start off by saying that I appreciate all the work people
are doing on the docs, *however*..

We don't want the documentation in the wiki. This is a quality control
issue; if the wiki is the place for official documentation, we have to
constantly check the wiki diffs and roll back any changes we disagree
with. This is obviously problematic because:

 1. We can't at any time be sure that the docs are correct.
 2. We have no good way to discuss the changes.
 3. It creates a lot of extra maintenance work for us.

Other than that ReST is proven and powerful, much more so than trac's
own wiki-markup.

Ideally I would like doc changes to be submitted as patches attached to
enhancement tickets. That gives us an easy way to review the changes
before commiting anything to the trunk.

If anyone intends to put a lot of work into the docs, it might be
possible to create a branch for that. That would make it even simpler to
review the changes.

Regards,
--
Daniel Wallin
[hidden email]
http://www.rasterbar.com


-------------------------------------------------------------------------
Using Tomcat but need to do more? Need to support web services, security?
Get stuff done quickly with pre-integrated technology to make your job easier.
Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642
_______________________________________________
luabind-user mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/luabind-user
Reply | Threaded
Open this post in threaded view
|

Re: Docs and the wiki

Jason McKesson
I assume that, by "we", you are referring to the official Luabind
developers. And thus, when I say "you," I'm referring to the official
Luabind developers as a group.

I'm not quite sure I understand your point of view here.

>From what I understand, Luabind is in a fairly nebulous state
currently. From statements I have gathered here on this message board,
Luabind's developers no longer have the time to significantly improve
Luabind. Their contributions in the future will be in terms of bug
fixing and keeping Luabind functioning with new versions of Lua. Even
making point releases (actual releases of Luabind, not merely checking
stuff into CVS) seems to currently be beyond the developers. Lua 5.1
has been out for about a year, and the official release of Luabind
does not support it.

And that's OK, from my perspective. I understand that you have more
important things going on than Luabind.

However, you can't have things both ways. If you're not able to devote
the time to the various aspects of Luabind's development that it
deserves, OK. But, in doing so, I don't understand how you get to have
final say over what is and is not Luabind's official documentation. I
mean, you're supposed to be not devoting much time to Luabind; how are
you going have the time to properly review any such documentation
(especially if that documentation is as long as it needs to be to be
truly comprehensive)?

Furthermore, I would also suggest that, from a practical standpoint,
there are more effective things for the developers to be doing with
their limited Luabind development time than reviewing documentation.
Documenting the internals (so that others can come along and
understand how to make improvements/changes without having to be
metaprogramming gurus) would be my preference, but there are other
alternatives as well.

I understand the wish to maintain the quality of the Luabind
documentation. What I fail to understand is why this can't (or
shouldn't) be the responsibility of the Luabind community itself,
rather than having to fall to the Luabind developers (who, as
previously stated, don't really have the time for it).

On 2/1/07, Daniel Wallin <[hidden email]> wrote:

> First, let me start off by saying that I appreciate all the work people
> are doing on the docs, *however*..
>
> We don't want the documentation in the wiki. This is a quality control
> issue; if the wiki is the place for official documentation, we have to
> constantly check the wiki diffs and roll back any changes we disagree
> with. This is obviously problematic because:
>
>  1. We can't at any time be sure that the docs are correct.
>  2. We have no good way to discuss the changes.
>  3. It creates a lot of extra maintenance work for us.
>
> Other than that ReST is proven and powerful, much more so than trac's
> own wiki-markup.
>
> Ideally I would like doc changes to be submitted as patches attached to
> enhancement tickets. That gives us an easy way to review the changes
> before commiting anything to the trunk.
>
> If anyone intends to put a lot of work into the docs, it might be
> possible to create a branch for that. That would make it even simpler to
> review the changes.
>
> Regards,
> --
> Daniel Wallin
> [hidden email]
> http://www.rasterbar.com
>
>
> -------------------------------------------------------------------------
> Using Tomcat but need to do more? Need to support web services, security?
> Get stuff done quickly with pre-integrated technology to make your job easier.
> Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo
> http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642
> _______________________________________________
> luabind-user mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/luabind-user
>

-------------------------------------------------------------------------
Using Tomcat but need to do more? Need to support web services, security?
Get stuff done quickly with pre-integrated technology to make your job easier.
Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642
_______________________________________________
luabind-user mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/luabind-user
Reply | Threaded
Open this post in threaded view
|

Re: Docs and the wiki

Tyler Olsen-2
I have to agree with Jason's comments, especially on prioritizing
documentation of the internals. If Daniel and Arvid insist on keeping
the "official" documentation under heavy scrutiny, then I think that the
community should at least be able to maintain their own unofficial
documentation on the trac wiki. I understand the desire to keep the docs
in ReST instead of the wiki, but you have to admit that it is easier for
a community to maintain documentation in a wiki rather than submit
documentation patches, since the result of editing is instantaneous.


In summary, here are my thoughts:

- Create an unofficial Luabind documentation in the wiki, maintained by
the community (and mostly ignored by the busy developers :)

- Keep the official documentation where it is, and only


Of course the disadvantage here is that we'll have two docs, one of
which (I'm assuming) will be more comprehensive but also more "buggy",
and another which will be the epitome of correctness but may be more
sparse or out of date. This is just a suggestion for a compromise
between what I see as the two extremes here. I'm not sure if it will
work out well, but I know I'll definitely help with any documentation
that is kept in the wiki.


- Tyler




-------------------------------------------------------------------------
Using Tomcat but need to do more? Need to support web services, security?
Get stuff done quickly with pre-integrated technology to make your job easier.
Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642
_______________________________________________
luabind-user mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/luabind-user
Reply | Threaded
Open this post in threaded view
|

Re: Docs and the wiki

bbguy
In reply to this post by Daniel Wallin-3
for god's sake somebody remove me from this list. i have tried a million times to unsubscribe, and even have gotten successful responses from the automation list but it continues to clutter my inbox.




> Date: Sat, 3 Feb 2007 01:53:57 -0600

> From: [hidden email]
> To: [hidden email]
> Subject: Re: [luabind] Docs and the wiki
>
> I have to agree with Jason's comments, especially on prioritizing
> documentation of the internals. If Daniel and Arvid insist on keeping
> the "official" documentation under heavy scrutiny, then I think that the
> community should at least be able to maintain their own unofficial
> documentation on the trac wiki. I understand the desire to keep the docs
> in ReST instead of the wiki, but you have to admit that it is easier for
> a community to maintain documentation in a wiki rather than submit
> documentation patches, since the result of editing is instantaneous.
>
>
> In summary, here are my thoughts:
>
> - Create an unofficial Luabind documentation in the wiki, maintained by
> the community (and mostly ignored by the busy developers :)
>
> - Keep the official documentation where it is, and only
>
>
> Of course the disadvantage here is that we'll have two docs, one of
> which (I'm assuming) will be more comprehensive but also more "buggy",
> and another which will be the epitome of correctness but may be more
> sparse or out of date. This is just a suggestion for a compromise
> between what I see as the two extremes here. I'm not sure if it will
> work out well, but I know I'll definitely help with any documentation
> that is kept in the wiki.
>
>
> - Tyler
>
>
>
>
> -------------------------------------------------------------------------
> Using Tomcat but need to do more? Need to support web services, security?
> Get stuff done quickly with pre-integrated technology to make your job easier.
> Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo
> http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642
> _______________________________________________
> luabind-user mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/luabind-user

-------------------------------------------------------------------------
Using Tomcat but need to do more? Need to support web services, security?
Get stuff done quickly with pre-integrated technology to make your job easier.
Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642
_______________________________________________
luabind-user mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/luabind-user
Reply | Threaded
Open this post in threaded view
|

Re: Docs and the wiki

Daniel Wallin-3
In reply to this post by Jason McKesson
Jason McKesson wrote:

> I assume that, by "we", you are referring to the official Luabind
> developers. And thus, when I say "you," I'm referring to the official
> Luabind developers as a group.
>
> I'm not quite sure I understand your point of view here.
>
>>From what I understand, Luabind is in a fairly nebulous state
> currently. From statements I have gathered here on this message board,
> Luabind's developers no longer have the time to significantly improve
> Luabind. Their contributions in the future will be in terms of bug
> fixing and keeping Luabind functioning with new versions of Lua. Even
> making point releases (actual releases of Luabind, not merely checking
> stuff into CVS) seems to currently be beyond the developers. Lua 5.1
> has been out for about a year, and the official release of Luabind
> does not support it.

My intent with this whole thing (setting up trac etc) is to become more
involved with luabind. I am closing tickets and working on my
refactoring branch, as best I can.

We are trying to work towards a point release with Lua 5.1 support, and
after that one for Boost 1.34 support.

> And that's OK, from my perspective. I understand that you have more
> important things going on than Luabind.
>
> However, you can't have things both ways. If you're not able to devote
> the time to the various aspects of Luabind's development that it
> deserves, OK. But, in doing so, I don't understand how you get to have
> final say over what is and is not Luabind's official documentation.

We get final say because we are the maintainers. Whether or not we are
devoting significant time to developing the code base we are still the
maintainers of this library. If you follow the procedure I have outlined
for you, I (or some other developer) will take the time necessary to
review any patches you come up with, documentation or code.

Just because the library doesn't have very active maintainers doesn't
mean it automatically enter into some state of anarchy where anyone get
write access.

> Furthermore, I would also suggest that, from a practical standpoint,
> there are more effective things for the developers to be doing with
> their limited Luabind development time than reviewing documentation.
> Documenting the internals (so that others can come along and
> understand how to make improvements/changes without having to be
> metaprogramming gurus) would be my preference, but there are other
> alternatives as well.

This simply won't happen. I don't have a lot of time to spare, and what
little time I have I don't want to spend documenting the internals (some
of which should be rewritten from scratch anyway). User documentation is
far more important than this.

We value correct documentation very highly, and thus want it to go
through proper review before making it to the user. I'm going to give
you a couple of examples from the wiki:

  http://code.rasterbar.com/luabind/wiki/docs/BasicUse

 "... through the use of the luabind::module command ..."

   luabind::module() is a function.

 #include "luabind\luabind.hpp"

   You should never ever use backslash in paths like that, and we use
   <> for including luabind headers.

 void register_functions(lua_State *pState)

   "pState" isn't a naming convention we use. It should be all
   lowercase, and no prefix.

This is just a couple of examples from a quick glance. Had this gone
through proper review these things would had been pointed out and
corrected. What do you suggest I do now? I don't have time to rewrite
this myself, and now there is documentation on one of our official
channels that we do not agree with. Should I just remove the page?
That's obviously not an efficient process. Can you see how this would
work better if you submitted patches?

It's *really* great that you want to contribute to this project, but
please do so with the procedures that I outlined earlier.

Regards,
--
Daniel Wallin
[hidden email]
http://www.rasterbar.com


-------------------------------------------------------------------------
Using Tomcat but need to do more? Need to support web services, security?
Get stuff done quickly with pre-integrated technology to make your job easier.
Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642
_______________________________________________
luabind-user mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/luabind-user
Reply | Threaded
Open this post in threaded view
|

Re: Docs and the wiki

Dave Wolfe
In reply to this post by Daniel Wallin-3
I believe the LuaBind documentation to be exemplary.  I find it to be
quite a bit more cogent than the docs for Boost.Python, the library that
inspired it.  I really appreciate that everything is all on one page,
and I don't have to go trolling thru some ad hoc collection of links to
find what I'm looking for.

I did have to join this mailing list to figure out how to get LuaBind
working with Lua 5.1.1, so the documentation could definitely stand to
be updated.   But keeping a wiki from becoming a tangled mess requires
constant vigilance, and Daniel and Arvid have said they don't have time
for this.  (See

My advice to people wanting to improve the LuaBind docs is:

1. Go to http://code.rasterbar.com/luabind/newticket and open a new
   ticket for any deficiency you find

2. If you're confident you can correct the deficiency yourself, download
   the docs from:

     - https://luabind.svn.sourceforge.net/svnroot/luabind/trunk/doc

   using, e.g, TortoiseSVN, and make whatever changes you believe are
   appropriate.  Then create a patch that encapsulates the change.  If
   using TortoiseSVN, you can simply right-click the file and choose
   'TortoiseSVN->Create patch'; otherwise, use the command 'svn diff
   [alteredFileName] > alteredFileName.patch'. Then skip to step #5.

3. If you're not sure what change to make, send an email to this list
   containing a link to the trac ticket you opened in step #1, and ask
   whether anyone has a suggestion for reworking the problematic piece
   of documentation.  Offer to submit a patch based on any responses
   received.

4. When/if someone posts a proposed change to the mailing list, download
   the docs as described in step #2, make the proposed change in your
   local copy, and create a patch based on it.

5. Attach the patch to the trac ticket created in step #1, and include a
   link back to any mailing list thread(s) discussing the change.

It is trivially easy for Daniel and/or Arvid to QA patches submitted
this way, so I'm sure they'll process them in a timely manner.  And I
think the authors have earned the right to suggest what the work flow
for this ought to be.  May I suggest that we all try to do things this
way for awhile and see how it goes?



-------------------------------------------------------------------------
Using Tomcat but need to do more? Need to support web services, security?
Get stuff done quickly with pre-integrated technology to make your job easier.
Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642
_______________________________________________
luabind-user mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/luabind-user
Reply | Threaded
Open this post in threaded view
|

Re: Docs and the wiki

Jason McKesson
In reply to this post by Daniel Wallin-3
Daniel Wallin wrote:
> This simply won't happen. I don't have a lot of time to spare, and what
> little time I have I don't want to spend documenting the internals (some
> of which should be rewritten from scratch anyway). User documentation is
> far more important than this.
>  
No, it is not.

What Luabind needs right now more than anything is one or more
developers who can spend the time that Luabind deserves to turn it into
a first-class library. Luabind already has adequate documentation for
users (though it could be more comprehensive); spending precious
developer resources (ie: time) on improvements to them isn't terribly
helpful.

Further, the general attitude I'm sensing from you is antithetical to
Open Source Development as an ideal, and Luabind development as a
practical matter. That being, "I have this knowledge of how the code
works, and it's not terribly important that someone else does, even
though I don't have the proper time to devote to the project."
Disseminating this information will only serve to improve Luabind, as
you're far more likely to find someone who does have the time to
properly maintain and improve the library if you explain how the
byzantine internals work. Finding this person or people is the first
step towards improving Luabind, and anything that helps that process
along is the most important thing you can be doing for Luabind.

This "rewrite from scratch" that you refer to, who's going to be doing
that? You clearly state that you don't have the time for it (at least,
not to do it in reasonable expected time). And only someone familiar
with Luabind's internals as they are now can devise a proper refactoring
of them. So, there's this catch-22 that guarantees that this rewrite
will never happen.

Or, at least, not without internal code documentation.
> This is just a couple of examples from a quick glance. Had this gone
> through proper review these things would had been pointed out and
> corrected. What do you suggest I do now? I don't have time to rewrite
> this myself, and now there is documentation on one of our official
> channels that we do not agree with. Should I just remove the page?
> That's obviously not an efficient process. Can you see how this would
> work better if you submitted patches?
>  
Only in the sense that the documentation behaves as you want it to,
which may be opposed to being what it needs to be for the users.

For example, the thing about me calling the luabind::module function a
command. I called it that for a very specific reason: this is beginner
documentation.

Luabind's binding code doesn't look like C++ on the surface. Attempting
to learn how it actually is C++ is not conducive to getting a beginner
up and running. Knowing that luabind::module is technically a C++
function call is not only superfluous language at this stage, it is
actually detrimental towards getting a beginner to understand what to do
to bind C++ code to Lua. In begs the question, "Um, it kinda looks like
a function call, but last time I checked, [] wasn't legal after a
function call...," rather than focusing the user on getting their code
to work.

Later in the documentation, after the user has read and understood how
to bind other things and has gotten used to it, one could go into detail
in explaining what luabind::module really is, why you use [] afterwards,
what '.def' technically is, and all of that.

While I might agree with the forward slash/backslash thing, allow me to
quote from your own installation documents:

"If you are using Visual Studio it may be easier to include the files in
the src directory in your project."

While I might point out that not having a smooth build process for
Visual Studio is not a wise idea (unfortunately, Lua doesn't either),
the more important fact is that you're telling VS users to not use
Luabind as a compiled library. Which means that the '<>' notation is
entirely inappropriate for them.

In a general sense, submitting a "patch" isn't useful, because I'm not
patching anything. In effect, I'm rewriting it from scratch, using the
original as a general guideline. So basically, it's submitting
documentation for review.

One of the advantages of using a Wiki is that you don't have to babysit
the docs. If someone feels that calling luabind::module a "command" is
inappropriate, then they can go in and change it. What it does mean is
that it will never be what any one person believes it should be. Having
to submit "patches" for review for inclusion in a Wiki violates the
entire purpose of having a Wiki to begin with (which is allowing anyone
to make unmoderated comments).

-------------------------------------------------------------------------
Using Tomcat but need to do more? Need to support web services, security?
Get stuff done quickly with pre-integrated technology to make your job easier.
Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642
_______________________________________________
luabind-user mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/luabind-user
Reply | Threaded
Open this post in threaded view
|

Re: Docs and the wiki

Dave Wolfe
In reply to this post by Daniel Wallin-3
Jason McKesson <[hidden email]> wrote:

> One of the advantages of using a Wiki is that you don't have to
> babysit the docs.

A lot of experienced Open Source software developers would disagree with
you on that point:

  - http://producingoss.com/html-chunk/wikis.html

Failure to police a wiki's contents results in a jumbled, disjointed
mess. If my name and reputation were directly associated with LuaBind,
I'd also be reticent to go this route.

Please, let's find a way contribute that permits the authors---or
some trusted person(s) they designate---to QA contributions and weed out
duplicated or erroneous information.  It's really the only way to assure
consistent, high-quality documentation...



-------------------------------------------------------------------------
Using Tomcat but need to do more? Need to support web services, security?
Get stuff done quickly with pre-integrated technology to make your job easier.
Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642
_______________________________________________
luabind-user mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/luabind-user
Reply | Threaded
Open this post in threaded view
|

Re: Docs and the wiki

Arvid Norberg-2
In reply to this post by Jason McKesson
On Feb 4, 2007, at 11:44 , Jason McKesson wrote:

> [...]
> Further, the general attitude I'm sensing from you is antithetical to
> Open Source Development as an ideal, and Luabind development as a
> practical matter. That being, "I have this knowledge of how the code
> works, and it's not terribly important that someone else does, even
> though I don't have the proper time to devote to the project."
> Disseminating this information will only serve to improve Luabind, as
> you're far more likely to find someone who does have the time to
> properly maintain and improve the library if you explain how the
> byzantine internals work. Finding this person or people is the first
> step towards improving Luabind, and anything that helps that process
> along is the most important thing you can be doing for Luabind.

I'm pretty sure me or daniel (or somebody else with luabind  
knowledge) could answer questions regarding the internals if anyone's  
interested in knowing something. To actually write a document  
describing all of it is a lot more work though. The luabind code is  
commented (maybe sparsely in some places), and I would say that it's  
not impossible to understand it without having it explained in a  
document. Quite frankly, knowing template meta programming is more or  
less a requirement anyway.

> This "rewrite from scratch" that you refer to, who's going to be doing
> that? You clearly state that you don't have the time for it (at least,
> not to do it in reasonable expected time). And only someone familiar
> with Luabind's internals as they are now can devise a proper  
> refactoring
> of them. So, there's this catch-22 that guarantees that this rewrite
> will never happen.
>
> Or, at least, not without internal code documentation.
>> This is just a couple of examples from a quick glance. Had this gone
>> through proper review these things would had been pointed out and
>> corrected. What do you suggest I do now? I don't have time to rewrite
>> this myself, and now there is documentation on one of our official
>> channels that we do not agree with. Should I just remove the page?
>> That's obviously not an efficient process. Can you see how this would
>> work better if you submitted patches?
>>
> Only in the sense that the documentation behaves as you want it to,
> which may be opposed to being what it needs to be for the users.
>
> For example, the thing about me calling the luabind::module function a
> command. I called it that for a very specific reason: this is beginner
> documentation.
>
> Luabind's binding code doesn't look like C++ on the surface.  
> Attempting
> to learn how it actually is C++ is not conducive to getting a beginner
> up and running. Knowing that luabind::module is technically a C++
> function call is not only superfluous language at this stage, it is
> actually detrimental towards getting a beginner to understand what  
> to do
> to bind C++ code to Lua. In begs the question, "Um, it kinda looks  
> like
> a function call, but last time I checked, [] wasn't legal after a
> function call...," rather than focusing the user on getting their code
> to work.
>
> Later in the documentation, after the user has read and understood how
> to bind other things and has gotten used to it, one could go into  
> detail
> in explaining what luabind::module really is, why you use []  
> afterwards,
> what '.def' technically is, and all of that.
>
> While I might agree with the forward slash/backslash thing, allow  
> me to
> quote from your own installation documents:
>
> "If you are using Visual Studio it may be easier to include the  
> files in
> the src directory in your project."
>
> While I might point out that not having a smooth build process for
> Visual Studio is not a wise idea

You are welcome to become the maintainer of such a project (file).  
But we don't use developer studios IDE and we prefer to just maintain  
build files for a single build system, so we chose a multi platform /  
multi compiler one.

> (unfortunately, Lua doesn't either),
> the more important fact is that you're telling VS users to not use
> Luabind as a compiled library. Which means that the '<>' notation is
> entirely inappropriate for them.

I don't really see the relation between <> and compiling the library  
in a separate build step. In my experience it is usually best to  
build everything in the same visual studio project, since it won't  
detect prebuilt libraries that are link-incompatible.

Or just build everything in boost-build.

cheers,
--
Arvid Norberg



-------------------------------------------------------------------------
Using Tomcat but need to do more? Need to support web services, security?
Get stuff done quickly with pre-integrated technology to make your job easier.
Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642
_______________________________________________
luabind-user mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/luabind-user