doc hacking at Hack Day at CCC13

[Daan Hoogland <da...@gmail.com>]

To all of you planning to hack away at documentation:

There is quite a lot of commeted out code. And there is quite a lot of code
uncommented; classes and public/protected and package scope methods without
description. I have not taken up the job of improving on this. Instead I
have been swearing at others for it, for which i apologise.

Both Joe Brockmeier and Mike Tutkowski have useful proposals for doc
improvement and I want to call on them to devise doc-from-code generation
tooling to achieve their goals. (but i call not just on them of course)

now shoot me,
Daan Hoogland

RE: doc hacking at Hack Day at CCC13

[Radhika Puthiyetath <ra...@citrix.com>]

+1

Great idea...

-----Original Message-----
From: Daan Hoogland [mailto:daan.hoogland@gmail.com] 
Sent: Saturday, June 15, 2013 7:58 PM
To: dev
Subject: doc hacking at Hack Day at CCC13

To all of you planning to hack away at documentation:

There is quite a lot of commeted out code. And there is quite a lot of code uncommented; classes and public/protected and package scope methods without description. I have not taken up the job of improving on this. Instead I have been swearing at others for it, for which i apologise.

Both Joe Brockmeier and Mike Tutkowski have useful proposals for doc improvement and I want to call on them to devise doc-from-code generation tooling to achieve their goals. (but i call not just on them of course)

now shoot me,
Daan Hoogland

Re: doc hacking at Hack Day at CCC13

[Daan Hoogland <da...@gmail.com>]

Ok, this is not what I mean, though it wouldn't hurt having that kind of
info at hand in the source tree with links to and from code. I do mean:
1 class diagrams, though not all relations can be generated from source
2 javadocs at least on class level

regards,



On Mon, Jun 17, 2013 at 8:44 PM, Joe Brockmeier <jz...@zonker.net> wrote:

>
>
> On Sat, Jun 15, 2013, at 09:27 AM, Daan Hoogland wrote:
> > To all of you planning to hack away at documentation:
> >
> > There is quite a lot of commeted out code. And there is quite a lot of
> > code
> > uncommented; classes and public/protected and package scope methods
> > without
> > description. I have not taken up the job of improving on this. Instead I
> > have been swearing at others for it, for which i apologise.
> >
> > Both Joe Brockmeier and Mike Tutkowski have useful proposals for doc
> > improvement and I want to call on them to devise doc-from-code generation
> > tooling to achieve their goals. (but i call not just on them of course)
>
> Can you expand on this?
>
> We already generate API docs from the code. Generally when I talk about
> docs, I'm referring to implementation docs - e.g. "how do I set up,
> install, and manage CloudStack" docs.
>
> Best,
>
> jzb
> --
> Joe Brockmeier
> jzb@zonker.net
> Twitter: @jzb
> http://www.dissociatedpress.net/
>

Re: doc hacking at Hack Day at CCC13

[Joe Brockmeier <jz...@zonker.net>]

On Sat, Jun 15, 2013, at 09:27 AM, Daan Hoogland wrote:
> To all of you planning to hack away at documentation:
> 
> There is quite a lot of commeted out code. And there is quite a lot of
> code
> uncommented; classes and public/protected and package scope methods
> without
> description. I have not taken up the job of improving on this. Instead I
> have been swearing at others for it, for which i apologise.
> 
> Both Joe Brockmeier and Mike Tutkowski have useful proposals for doc
> improvement and I want to call on them to devise doc-from-code generation
> tooling to achieve their goals. (but i call not just on them of course)

Can you expand on this? 

We already generate API docs from the code. Generally when I talk about
docs, I'm referring to implementation docs - e.g. "how do I set up,
install, and manage CloudStack" docs.

Best,

jzb
-- 
Joe Brockmeier
jzb@zonker.net
Twitter: @jzb
http://www.dissociatedpress.net/