Re: [GSoC Mentors] Announcing Season of Docs 2019

[Rik]

On 03/12/2019 05:16 AM, address@hidden wrote:

Subject:

Re: [GSoC Mentors] Announcing Season of Docs 2019

From:

Nicholas Jankowski <address@hidden>

Date:

03/12/2019 05:04 AM

To:

Carlo de Falco <address@hidden>

CC:

octave maintainers mailing list <address@hidden>, Nir Krakauer <address@hidden>

List-Post:

<mailto:address@hidden>

Precedence:

list

MIME-Version:

1.0

References:

<address@hidden> <address@hidden>

In-Reply-To:

<address@hidden>

Message-ID:

<address@hidden>

Content-Type:

multipart/alternative; boundary="0000000000003896700583e47f68"

Message:

3

On Tue, Mar 12, 2019, 6:32 AM c. <address@hidden> wrote:

Nir,

Shall we apply? I think for example documenting liboctave API would be a great project ....

c.

Can't hurt to apply.  Compared to other programs Octave's documentation is pretty extensive. Are there other areas its known to be deficient?

Absolutely.  We don't have comprehensive documentation of the classdef interface.  The old @class format *is* documented, but hardly anyone uses that.

I'd like to see the documentation that describes the visual functions all have at least one example image.  For example, the colormaps are described in words, but that is really no help at all.  You need to see what a colormap looks like.  An easy thing to do would be to run the colormap demo #1 and display that image in the documentation.  That might be more of a coding project, than a technical writer's project though.

I'd like to see separate documentation for plot markers and line styles so that something like "help linestyle" would return something.  And then I'd like the graphics documentation reviewed and cross-references to this documentation place in the manual.  Currently, we often say something like "See @code{plot} for a description of marker and line styles".

Also, if you use the selection tool on the Savannah bug tracker you can find a fair number of bugs that are just about documentation.  They often just need someone to write up text that is clear as to a function's purpose and method of use.

Anything applicable to new users or would-be developers? 

Worth a separate section of the wiki to collect suggestions?

Possibly, but also look on the bug tracker.

--Rik