Quantcast

Code Health Tuesday - documentation!

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Code Health Tuesday - documentation!

Matt Caswell-2

Hi all

Our next "Code Health Tuesday" event will be on Tuesday 28th March.

We've seen some great contributions during our last two events with many
significant improvements merged as a result. We'd like to continue that
trend with our next theme - documentation.

Just find some missing documentation, write it and send us a PR on our
github site. Or help us fix incorrect or out-of-date documentation, or
broken links, etc.

Thanks!

Matt


FAQ:

Q: How do I participate?
A: Find something to document. Create a Github pull request and  put
“code health” in the title. We’ll be monitoring Github for quick turnaround.

Q: Which branches should I target?
A: You should target master. If documentation applies to earlier
releases then please indicate which ones in the PR. Sometimes there are
subtle differences between the different releases, so it may be
necessary to create a different PR for older branches.

Q: What form should the documentation take?
A: All our documentation is in POD file format. Take a look in the doc
directory and read a few of the pages to get used to our style. The
doc/man3/BIO_printf.pod file is a good, recently written example. If you
are providing missing documentation consider whether it should appear in
a new POD file, or whether it should be added to an existing one.
You can use the "doc-nits" script to run some basic checks on the
documentation you have written (run "make doc-nits").

Q: Do you have any tools to find what to document?
A: Yes, the doc-nits tool (in the util sub-dir) can provide some useful
info:
    ./util/find-doc-nits –l (references to non-existing POD pages)
    ./util/find-doc-nits –u (all undocumented public functions)
--
openssl-dev mailing list
To unsubscribe: https://mta.openssl.org/mailman/listinfo/openssl-dev
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Code Health Tuesday - documentation!

Matt Caswell-2
Just a reminder about this event taking place tomorrow!

Matt

On 23/03/17 17:57, Matt Caswell wrote:

>
> Hi all
>
> Our next "Code Health Tuesday" event will be on Tuesday 28th March.
>
> We've seen some great contributions during our last two events with many
> significant improvements merged as a result. We'd like to continue that
> trend with our next theme - documentation.
>
> Just find some missing documentation, write it and send us a PR on our
> github site. Or help us fix incorrect or out-of-date documentation, or
> broken links, etc.
>
> Thanks!
>
> Matt
>
>
> FAQ:
>
> Q: How do I participate?
> A: Find something to document. Create a Github pull request and  put
> “code health” in the title. We’ll be monitoring Github for quick turnaround.
>
> Q: Which branches should I target?
> A: You should target master. If documentation applies to earlier
> releases then please indicate which ones in the PR. Sometimes there are
> subtle differences between the different releases, so it may be
> necessary to create a different PR for older branches.
>
> Q: What form should the documentation take?
> A: All our documentation is in POD file format. Take a look in the doc
> directory and read a few of the pages to get used to our style. The
> doc/man3/BIO_printf.pod file is a good, recently written example. If you
> are providing missing documentation consider whether it should appear in
> a new POD file, or whether it should be added to an existing one.
> You can use the "doc-nits" script to run some basic checks on the
> documentation you have written (run "make doc-nits").
>
> Q: Do you have any tools to find what to document?
> A: Yes, the doc-nits tool (in the util sub-dir) can provide some useful
> info:
>     ./util/find-doc-nits –l (references to non-existing POD pages)
>     ./util/find-doc-nits –u (all undocumented public functions)
>
--
openssl-dev mailing list
To unsubscribe: https://mta.openssl.org/mailman/listinfo/openssl-dev
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Code Health Tuesday - documentation!

Matt Caswell-2
In reply to this post by Matt Caswell-2


On 23/03/17 17:57, Matt Caswell wrote:
> Our next "Code Health Tuesday" event will be on Tuesday 28th March.
>
> We've seen some great contributions during our last two events with many
> significant improvements merged as a result. We'd like to continue that
> trend with our next theme - documentation.
>
> Just find some missing documentation, write it and send us a PR on our
> github site. Or help us fix incorrect or out-of-date documentation, or
> broken links, etc.

We held another successful event yesterday. We saw a wide variety of
submissions - all focussed on improving our documentation, from simple
typos and grammar fixes, to missing command line option documentation
and whole new pod pages.

There were 16 PRs raised during the event, of which all but 1 have now
been pushed through to closure. The "find-doc-nits" script tells me that
those PRs provided new documentation for 30 public API functions!!

Many thanks to all those that took part.

Matt
--
openssl-dev mailing list
To unsubscribe: https://mta.openssl.org/mailman/listinfo/openssl-dev
Loading...