Re: Plea to help flag docs

Hi Boris,

On 07/11/2013 10:30 AM, Boris Vassilev wrote:
> Hi Anne,
>
> Previously I have made small corrections to the documentation by submitting
> a GIT patch-set. In principle, is this somehow inferior to using the
> tagging system? It seems easier: correct or expand, then submit to a
> maintainer so that it can be validated. It does not seem like more work and
> the changes are nicely incremental. Is there something I'm missing?

Yes and no (or maybe :-) First of all, the documentation is spread all
over the system using a mixture of LaTeX, PlDoc wiki files and PlDoc
from the source code. For many people it is a bit too much to download
the source, learn git and find the location of this specific bit of the
documentation. Then, other parts of the web site are in the web site's
git.

The direct annotation that is provided since a few weeks allows for
quickly adding tags and comments to individual pages. They are
immediately visible to all visitors. The intend was twofold:

   - Get tags to make things findable that are otherwise not.  Many
     people have been asking for things like `Pause', which is called
     sleep/1, `Exit', which is called halt/1, etc.

   - Get examples.  That is the primary reason for having the annotation
     field.  Editing uses a PlDoc wiki editor with preview facilities.
     You can also use this to clarify missing bits or ambiguities of the
     documentation.  Most likely, such clarifications sooner or later
     will be added to the main text and the annotation can be removed.
     Examples will probably be left untouched.

You can login using your google or yahoo account, or in fact any OpenID
provider (I will block providers if they are mostly used by spammers).
You can stay logged in. Note that your profile page shows all tags and
annotations that you created. This allows using these facilities as your
notes and bookmark list.

So, please use these facilities and help improving them, either by hacking
or suggesting new features.

	Cheers --- Jan

P.s.	Of course, git patches are still much appreciated!


>
> Cheers,
> Boris
>
>
> On Thu, Jul 11, 2013 at 10:54 AM, Wouter Beek <[email protected]> wrote:
>
>> Hi Anne,
>>
>> I think this is a very good initiative: using the Prolog community to
>> improve the already-quite-good documentation system!
>>
>> It sometimes occurs to me that predicates are well-documented but that an
>> example would greatly ease the use of that predicate by a wider range of
>> programmers. Related to this, I often see questions on the Prolog mailing
>> list the answers to which could be used to enrich the documentation as well
>> (especially when they provide a nice code example of 2 or 3 lines that
>> immediately clarifies the problem at hand).