Help with documentation

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

Help with documentation

John Phillips-4
   If you have a great idea for a library, but you don't feel the
documentation is keeping to the same high standards, there is now a
place to look.
   If you are frustrated by the documentation of a library and would
love a chance to help make it better, there is now a place to offer your
services.

   On the Wiki, you will now find a link to Documentation Helpers. This
is a list of people who are volunteering to work with developers to
improve the documentation of libraries and proposed libraries.
   If you want to help, go add your name to the list. If you want help,
go look at the list and contact someone.

   Since this is the result of a conversation buried deep in a thread
that some people may not be following, I'm also putting it in its own
thread.

                        John Phillips

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Help with documentation

David Maisonave
"John Phillips" <[hidden email]> wrote in message
news:<drvqjs$3ls$[hidden email]>...
>    If you have a great idea for a library, but you don't feel the
> documentation is keeping to the same high standards, there is now a
> place to look.
>    If you are frustrated by the documentation of a library and would
> love a chance to help make it better, there is now a place to offer
your
> services.
>
>    On the Wiki, you will now find a link to Documentation Helpers.
> This
> is a list of people who are volunteering to work with developers to
> improve the documentation of libraries and proposed libraries.
>    If you want to help, go add your name to the list. If you want
help,
> go look at the list and contact someone.
>
>    Since this is the result of a conversation buried deep in a thread
> that some people may not be following, I'm also putting it in its own
> thread.

Could you please provide a link for those of us who don't know what is
Wiki?
Thanks

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Help with documentation

elviin
In reply to this post by John Phillips-4
>    If you are frustrated by the documentation of a library and would
> love a chance to help make it better, there is now a place to offer your
> services.

Even if I'm not a native English speaker? Is there any way how can I
help with documentation?
At least I can read it:)

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Help with documentation

Paul Giaccone
In reply to this post by John Phillips-4
John Phillips wrote:

>   If you have a great idea for a library, but you don't feel the
>documentation is keeping to the same high standards, there is now a
>place to look.
>   If you are frustrated by the documentation of a library and would
>love a chance to help make it better, there is now a place to offer your
>services.
>
>   On the Wiki, you will now find a link to Documentation Helpers. This
>is a list of people who are volunteering to work with developers to
>improve the documentation of libraries and proposed libraries.
>   If you want to help, go add your name to the list. If you want help,
>go look at the list and contact someone.
>
>   Since this is the result of a conversation buried deep in a thread
>that some people may not be following, I'm also putting it in its own
>thread.
>  
>

I'd be happy to do this.  Can you provide a link?


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Help with documentation

David Abrahams
Paul Giaccone <[hidden email]> writes:

> John Phillips wrote:
>
>>   If you have a great idea for a library, but you don't feel the
>>documentation is keeping to the same high standards, there is now a
>>place to look.
>>   If you are frustrated by the documentation of a library and would
>>love a chance to help make it better, there is now a place to offer your
>>services.
>>
>>   On the Wiki, you will now find a link to Documentation Helpers. This
>>is a list of people who are volunteering to work with developers to
>>improve the documentation of libraries and proposed libraries.
>>   If you want to help, go add your name to the list. If you want help,
>>go look at the list and contact someone.
>>
>>   Since this is the result of a conversation buried deep in a thread
>>that some people may not be following, I'm also putting it in its own
>>thread.
>>  
>>
>
> I'd be happy to do this.  Can you provide a link?

http://www.crystalclearsoftware.com/cgi-bin/boost_wiki/wiki.pl
http://www.crystalclearsoftware.com/cgi-bin/boost_wiki/wiki.pl?Documentation_Helpers

--
Dave Abrahams
Boost Consulting
www.boost-consulting.com

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Help with documentation

John Phillips-4
David Abrahams wrote:

> Paul Giaccone <[hidden email]> writes:
>

>>
>>I'd be happy to do this.  Can you provide a link?
>
>
> http://www.crystalclearsoftware.com/cgi-bin/boost_wiki/wiki.pl
> http://www.crystalclearsoftware.com/cgi-bin/boost_wiki/wiki.pl?Documentation_Helpers
>

   Thanks, Dave, for getting there before me.
   Everyone should also remember that there is a link to the Wiki on the
Boost main web page, in case these links from Dave get lost.

                        John

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Help with documentation

John Phillips-4
In reply to this post by elviin
elviin wrote:

>>   If you are frustrated by the documentation of a library and would
>>love a chance to help make it better, there is now a place to offer your
>>services.
>
>
> Even if I'm not a native English speaker? Is there any way how can I
> help with documentation?
> At least I can read it:)
>
> _______________________________________________
> Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
>

   To me, the idea of having non-native English speakers look at the
docs to see if they are clear enough sounds like a good one. Boost isn't
a resource for only native English speakers, so if there is something
reasonable that can be done to make it more accessible, it should be
considered.

                        John

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Help with documentation

David Maisonave
In reply to this post by John Phillips-4
"John Phillips" <[hidden email]> wrote in message
news:<ds0csn$fpl$[hidden email]>...
> elviin wrote:
>
> >>   If you are frustrated by the documentation of a library and would

> >>love a chance to help make it better, there is now a place to offer
> >>your services.
> >
> >
> > Even if I'm not a native English speaker? Is there any way how can I

> > help with documentation? At least I can read it:)
> >
> > _______________________________________________
> > Unsubscribe & other changes:
> > http://lists.boost.org/mailman/listinfo.cgi/boost
> >
>
>    To me, the idea of having non-native English speakers look at the
> docs to see if they are clear enough sounds like a good one. Boost
isn't
> a resource for only native English speakers, so if there is something
> reasonable that can be done to make it more accessible, it should be
> considered.

This is another good reason why examples are so important.
A non-english developer can still figure out how to use an interface, if
a good example is included in the document.

There's been plenty of times when I've been able to use non-english web
sites, because they provided good example source code.

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Help with documentation

David Abrahams
In reply to this post by John Phillips-4
John Phillips <[hidden email]> writes:

> David Abrahams wrote:
>
>> Paul Giaccone <[hidden email]> writes:
>>
>
>>>
>>>I'd be happy to do this.  Can you provide a link?
>>
>>
>> http://www.crystalclearsoftware.com/cgi-bin/boost_wiki/wiki.pl
>> http://www.crystalclearsoftware.com/cgi-bin/boost_wiki/wiki.pl?Documentation_Helpers
>>
>
>    Thanks, Dave, for getting there before me.
>    Everyone should also remember that there is a link to the Wiki on the
> Boost main web page, in case these links from Dave get lost.

That's how I found it :)

--
Dave Abrahams
Boost Consulting
www.boost-consulting.com

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Help with documentation

Beman Dawes
In reply to this post by John Phillips-4

"John Phillips" <[hidden email]> wrote in message
news:ds0csn$fpl$[hidden email]...

> elviin wrote:
>
>>>   If you are frustrated by the documentation of a library and would
>>>love a chance to help make it better, there is now a place to offer your
>>>services.
>>
>>
>> Even if I'm not a native English speaker? Is there any way how can I
>> help with documentation?
>> At least I can read it:)
>>
>> _______________________________________________
>> Unsubscribe & other changes:
>> http://lists.boost.org/mailman/listinfo.cgi/boost
>>
>
>   To me, the idea of having non-native English speakers look at the
> docs to see if they are clear enough sounds like a good one. Boost isn't
> a resource for only native English speakers, so if there is something
> reasonable that can be done to make it more accessible, it should be
> considered.

FWIW, the C++ committee sets up a small ad hoc drafting committee at each
meeting to read formal motions to ensure the wording is OK. They always try
to include at least one person who is not a native English speaker.

Reporting weaknesses in documentation is one of the more valuable ways to
help out with Boost. And fixes for any problems found are especially
appreciated.

--Beman



_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost