# Git and Documentation 7 messages from 2010-08-09 to 2010-08-11. Participants: Sultan Shakir, Ævar Arnfjörð Bjarmason, Tomas Carnecky, Michael Witten. Thread: https://gitlist.dev/t/24684 ## Sultan Shakir, 2010-08-09 17:35 Subject: Git and Documentation Message-ID: URL: https://gitlist.dev/e/AANLkTi%3DP%3DRsToSor%3DgiC%2BdgV24bPj7KJ3eRV1M5a%2BiuD%40mail.gmail.com In-Reply-To: ``` 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 ``` ## Ævar Arnfjörð Bjarmason, 2010-08-09 20:43 Subject: Re: Git and Documentation Message-ID: URL: https://gitlist.dev/e/AANLkTi%3Dpk4oXz84kWbHEzTUiWkTV5P4P9mTwzQbJG865%40mail.gmail.com In-Reply-To: ``` On Mon, Aug 9, 2010 at 17:35, Sultan Shakir 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? ``` ## Sultan Shakir, 2010-08-10 19:55 Subject: Re: Git and Documentation Message-ID: URL: https://gitlist.dev/e/AANLkTikwVfymGB8oEQUN%3D1LMWoif22p316mm%3DPzSxQwa%40mail.gmail.com In-Reply-To: ``` 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 wrote: > On Mon, Aug 9, 2010 at 17:35, Sultan Shakir 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? > ``` ## Tomas Carnecky, 2010-08-10 20:31 Subject: Re: Git and Documentation Message-ID: <4C61B737.50108@dbservice.com> URL: https://gitlist.dev/e/4C61B737.50108%40dbservice.com In-Reply-To: ``` 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 ``` ## Michael Witten, 2010-08-10 20:47 Subject: Re: Git and Documentation Message-ID: URL: https://gitlist.dev/e/AANLkTimK_ounhk1Qou02V_3%2BJjpY9Y5ZO3OO2uRn6A7k%40mail.gmail.com In-Reply-To: <4C61B737.50108@dbservice.com> ``` On Tue, Aug 10, 2010 at 15:31, Tomas Carnecky 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/ ``` ## Michael Witten, 2010-08-10 20:56 Subject: Re: Git and Documentation Message-ID: URL: https://gitlist.dev/e/AANLkTikK6_MqPQSg944DNfVULT3ccN9xMsObCAqHqxY_%40mail.gmail.com In-Reply-To: ``` On Tue, Aug 10, 2010 at 15:47, Michael Witten wrote: > On Tue, Aug 10, 2010 at 15:31, Tomas Carnecky 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. ``` ## Sultan Shakir, 2010-08-11 16:34 Subject: Re: Git and Documentation Message-ID: URL: https://gitlist.dev/e/AANLkTinyHAkr7bd6Wsr-%3DMtxN1QT1r8tRCGJ94vhpBHP%40mail.gmail.com In-Reply-To: ``` On Tue, Aug 10, 2010 at 4:56 PM, Michael Witten wrote: > On Tue, Aug 10, 2010 at 15:47, Michael Witten wrote: >> On Tue, Aug 10, 2010 at 15:31, Tomas Carnecky 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. ```