[DOCS] Developer's Guide chapter on How to Write Docs

[Jessica Tomechak <je...@gmail.com>]

On Fri, Apr 5, 2013 at 2:05 AM, Sebastien Goasguen <ru...@gmail.com> wrote:

>
>
> FYI, in case you missed it, I wrote a chapter in the dev guide on how to
> write docs….
>
>
Sebastien,
I missed your "how to write docs" chapter at first, but noticed it in the
last month. I haven't done a close review, though. It basically covers the
same ground as our Doc Contributor's Wiki, plus some material from the
Publican User Guide, right?

I have been wondering whether it belongs in the Developer's Guide. The
Developer's Guide was intended for CS users who want to call the CS API,
like cloud owners who want to automate provisioning or get stats about the
cloud. The how-to-write-docs chapter seems like it's aimed at people who
are developing CS itself. The original intended audience of the book
shouldn't need to contribute to our docs...or should they?

Maybe the problem is the book title. It's been causing confusion ever since
CloudStack went into Apache. It should really be called "Using the
CloudStack API" or "Writing Applications On CloudStack" or something of
that nature.

OR else, perhaps we want to make this book aim at ACS community, rather
than CS users. Either way, it needs a discussion, I think. Comments anyone?

Jessica T.

Re: [DOCS] Developer's Guide chapter on How to Write Docs

[Sebastien Goasguen <ru...@gmail.com>]

On Apr 9, 2013, at 9:12 PM, Jessica Tomechak <je...@gmail.com> wrote:

> On Fri, Apr 5, 2013 at 2:05 AM, Sebastien Goasguen <ru...@gmail.com> wrote:
> 
>> 
>> 
>> FYI, in case you missed it, I wrote a chapter in the dev guide on how to
>> write docs….
>> 
>> 
> Sebastien,
> I missed your "how to write docs" chapter at first, but noticed it in the
> last month. I haven't done a close review, though. It basically covers the
> same ground as our Doc Contributor's Wiki, plus some material from the
> Publican User Guide, right?

it covers how to write docs with docbook, build them with publican and translation.

> 
> I have been wondering whether it belongs in the Developer's Guide. The
> Developer's Guide was intended for CS users who want to call the CS API,

I am slowly changing this intent. I also added docs on cloudmonkey,devcloud and marvin

> like cloud owners who want to automate provisioning or get stats about the
> cloud. The how-to-write-docs chapter seems like it's aimed at people who
> are developing CS itself. The original intended audience of the book
> shouldn't need to contribute to our docs...or should they?

of course they *should*, or it would be better to say that they *can*. Anyone can contribute to any part of Cloudstack.

> 
> Maybe the problem is the book title. It's been causing confusion ever since
> CloudStack went into Apache. It should really be called "Using the
> CloudStack API" or "Writing Applications On CloudStack" or something of
> that nature.

I am fine with Developer's guide. We just need to add more information for developers.

> 
> OR else, perhaps we want to make this book aim at ACS community, rather
> than CS users. Either way, it needs a discussion, I think. Comments anyone?

the beauty of our docbook files, is that anyone can take them and build their own books,chapters, guides. 
Folks just need to write.

> 
> Jessica T.