Git and Documentation

Git and Documentation

[Sultan Shakir]

Dear Git Community:
My organization is exploring using Git to manage our code repository.
We also have a strong need for documentation of our code.  The code is
written in a proprietary language (Discern Explorer/CCL).  We looked
into Natural Docs but don't think we can combine it with Git.  Does
anyone know of an app where we can combine the power of Git and code
documentation in one?  Thank you. -Sultan

Re: Git and Documentation

[Ævar Arnfjörð Bjarmason]

On Mon, Aug 9, 2010 at 17:35, Sultan Shakir <sshakirflhosp@gmail.com> wrote:
> Dear Git Community:
> My organization is exploring using Git to manage our code repository.
> We also have a strong need for documentation of our code.  The code is
> written in a proprietary language (Discern Explorer/CCL).  We looked
> into Natural Docs but don't think we can combine it with Git.  Does
> anyone know of an app where we can combine the power of Git and code
> documentation in one?  Thank you. -Sultan

Can you be clearer. That question makes little sense.

You can keep your documentation *in* Git if it's in files that you can
keep in version control. So in that case you could keep it alongside
your code.

Can't you use this approach?

Re: Git and Documentation

[Sultan Shakir]

Yes I guess I could.  I am a little new at this.   I got the same idea
after watching Stephen Wood's video here:
http://developer.yahoo.com/yui/theater/video.php?v=woods-yuiconf2009-yuidoc
.  He had 3 rules/guidelines that might work if we use YUI Doc to
generate the documentation:

1) Generate documentation as part of the build
2) Don’t manually check documentation in to VCS (do it automatically)
3) Treat documentation comments like code

I am not sure how to make it run as part of my build process though.

On Mon, Aug 9, 2010 at 4:43 PM, Ævar Arnfjörð Bjarmason
<avarab@gmail.com> wrote:
> On Mon, Aug 9, 2010 at 17:35, Sultan Shakir <sshakirflhosp@gmail.com> wrote:
>> Dear Git Community:
>> My organization is exploring using Git to manage our code repository.
>> We also have a strong need for documentation of our code.  The code is
>> written in a proprietary language (Discern Explorer/CCL).  We looked
>> into Natural Docs but don't think we can combine it with Git.  Does
>> anyone know of an app where we can combine the power of Git and code
>> documentation in one?  Thank you. -Sultan
>
> Can you be clearer. That question makes little sense.
>
> You can keep your documentation *in* Git if it's in files that you can
> keep in version control. So in that case you could keep it alongside
> your code.
>
> Can't you use this approach?
>

Re: Git and Documentation

[Tomas Carnecky]

On 8/10/10 9:55 PM, Sultan Shakir wrote:
> Yes I guess I could.  I am a little new at this.   I got the same idea
> after watching Stephen Wood's video here:
> http://developer.yahoo.com/yui/theater/video.php?v=woods-yuiconf2009-yuidoc
> .  He had 3 rules/guidelines that might work if we use YUI Doc to
> generate the documentation:
> 
> 1) Generate documentation as part of the build
> 2) Don’t manually check documentation in to VCS (do it automatically)
> 3) Treat documentation comments like code
> 
> I am not sure how to make it run as part of my build process though.

Please don't top post.

If the documentation is generated as part of the build, then there is no
reason to have it part of the history - you can always rebuild it from
the source. For the same reason you don't put compiled source into git.

And how to generate the doc as part of the build? That's up to you and
very much depends on what build system you use.

tom

Re: Git and Documentation

[Michael Witten]

On Tue, Aug 10, 2010 at 15:31, Tomas Carnecky <tom@dbservice.com> wrote:
> If the documentation is generated as part of the build, then there is no
> reason to have it part of the history - you can always rebuild it from
> the source. For the same reason you don't put compiled source into git.

Well, theoretically.

According to:

  http://git.kernel.org/?p=git/git.git;a=blob_plain;f=MaintNotes;hb=todo

the git project's repository itself tracks generated documentation for
practical reasons:

  The "html" and "man" [branches] are
  autogenerated documentation from the
  tip of the "master" branch; the tip
  of "html" is extracted to be visible
  at kernel.org at:

    http://www.kernel.org/pub/software/scm/git/docs/

Re: Git and Documentation

[Michael Witten]

On Tue, Aug 10, 2010 at 15:47, Michael Witten <mfwitten@gmail.com> wrote:
> On Tue, Aug 10, 2010 at 15:31, Tomas Carnecky <tom@dbservice.com> wrote:
>> If the documentation is generated as part of the build, then there is no
>> reason to have it part of the history - you can always rebuild it from
>> the source. For the same reason you don't put compiled source into git.
>
> Well, theoretically.
>
> According to:
>
>  http://git.kernel.org/?p=git/git.git;a=blob_plain;f=MaintNotes;hb=todo
>
> the git project's repository itself tracks generated documentation for
> practical reasons:
>
>  The "html" and "man" [branches] are
>  autogenerated documentation from the
>  tip of the "master" branch; the tip
>  of "html" is extracted to be visible
>  at kernel.org at:
>
>    http://www.kernel.org/pub/software/scm/git/docs/
>

I should add that generating documentation is time consuming and often
requires brittle software; there's a lot to gain by having one system
produce the same output for virtually everyone else.

Re: Git and Documentation

[Sultan Shakir]

On Tue, Aug 10, 2010 at 4:56 PM, Michael Witten <mfwitten@gmail.com> wrote:
> On Tue, Aug 10, 2010 at 15:47, Michael Witten <mfwitten@gmail.com> wrote:
>> On Tue, Aug 10, 2010 at 15:31, Tomas Carnecky <tom@dbservice.com> wrote:
>>> If the documentation is generated as part of the build, then there is no
>>> reason to have it part of the history - you can always rebuild it from
>>> the source. For the same reason you don't put compiled source into git.
>>
>> Well, theoretically.
>>
>> According to:
>>
>>  http://git.kernel.org/?p=git/git.git;a=blob_plain;f=MaintNotes;hb=todo
>>
>> the git project's repository itself tracks generated documentation for
>> practical reasons:
>>
>>  The "html" and "man" [branches] are
>>  autogenerated documentation from the
>>  tip of the "master" branch; the tip
>>  of "html" is extracted to be visible
>>  at kernel.org at:
>>
>>    http://www.kernel.org/pub/software/scm/git/docs/
>>
>
> I should add that generating documentation is time consuming and often
> requires brittle software; there's a lot to gain by having one system
> produce the same output for virtually everyone else.
>

Thank you all.