Monday, September 28, 2015

I'm back...

Been traveling a bit, so haven't updated lately, but I've not been entirely idle. Have recently added
docs for with/without, loop LINEs, next, last, redo, state, and while/until.

I'm considering trying to consolidate the documentation efforts into something more coherent than what we have presently. It would be very nice to actually have it all in order for the Christmas release of Perl 6. But that's an actual commitment, so I'm not fully convinced yet... Watch this space for something resembling a decision!

In the meantime, I have a question for Perl 5 programmers or anyone else who would like to render an opinion:

What makes for good documentation?

One of the things people have liked about Perl is that, for many years, it has had good, extensive documentation. I'm now wondering about what it is that appeals to people and how those qualities can be usefully applied to documenting Perl 6.

Your thoughts?

2 comments:

  1. Welcome back, David.

    I have an opinion about documentation, regarding the way it is presented to the users.

    The current documentation of types it's very good, but it's quite hard to read. I think it would be much better to have the method names on a side, instead of having all of them at the top, because it's much harder to jump between different methods.

    For example:

    http://doc.perl6.org/type/Array

    would be much better if rendered something like:

    http://apidock.com/ruby/Array
    or
    http://ruby-doc.org/core-1.9.3/Array.html

    Thanks and please continue your good efforts.

    ReplyDelete
  2. One important question is whether it is tutorial documentation, (which has to flow), or reference, which needs to be comprehensive, (obstructing flow). A possible solution is a comprehensive tutorial, with very good indexing for reference.

    Some of the best documentation I've ever used was in Borland's C++ set. There were copious examples of every point, many of them directly usable in serious programs.

    ReplyDelete