mxnet-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Henri Yandell <he...@yandell.org>
Subject Re: Need for MXNet API documentation Standards/Guidelines
Date Thu, 04 May 2017 06:53:35 GMT
Sounds like good stuff.

We could get a wiki setup at Apache and document it there.

Something that mxnet.io doesn't currently do is talk about the project
development; it's focused on the product. If you look at most Apache
websites, they are a mix of product and project development (which
personally I think is confusing, so I'd suggest we still keep the two
distinct). Having a subsite called contributing/developers would be useful,
and a documentation section could be in there.

Your 1-4 sound good to me. Do you have an example/template?

Hen


On Wed, May 3, 2017 at 10:51 AM, Naveen Swamy <mnnaveen@gmail.com> wrote:

> Currently a group of us within Amazon are documenting and improving the
> MXNet APIs to make it easier for users to build products/models.
>
> From my experience of this exercise, I see that as MXNet grows with more
> contributors joining in and develop new APIs, It is essential that we
> enforce and set guidelines that APIs come with some amount of documentation
> which will help the user to build models/products quickly instead of having
> to experiment with the APIs to understand their behavior.
>
> Since we have contributors around the world whose native language is not
> English, we do not have to go to the extent of getting the perfectly
> correct documentation(we can fix grammar and alike as a part of the PR
> ourselves before merging or educate the contributors), we have to be
> careful not to discourage the contributors just to have perfect
> documentation.
>
> Also I think documenting the APIs cannot be an after-thought or a one-time
> exercise.
>
> I think we need the following at a minimum documentation when an API is
> developed.
>
> 1. Follow documentation standard.
> 2. A clear description of what the API is.
> 3. A clear description of the parameters.
> 4. Examples in(Python?) to show the usage and clarify the parameters/API.
>
> open to comments/suggestions ?
>
> Thanks, Naveen
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message