{"thread":{"id":"24684","subject":"Git and Documentation","startedAt":"2010-08-09T17:35:39Z","lastAt":"2010-08-11T16:34:20Z","messageCount":7,"participants":["Sultan Shakir","Ævar Arnfjörð Bjarmason","Tomas Carnecky","Michael Witten"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"147545","messageId":"AANLkTi=P=RsToSor=giC+dgV24bPj7KJ3eRV1M5a+iuD@mail.gmail.com","threadId":"24684","inReplyTo":"AANLkTik_rO_+az5kE=yhfXK1uUO3v0RKdcO2hzFBcZym@mail.gmail.com","subject":"Git and Documentation","fromName":"Sultan Shakir","fromEmail":"sshakirflhosp@gmail.com","sentAt":"2010-08-09T17:35:39Z","receivedAt":"2010-08-09T17:35:39Z","isPatch":false,"sender":{"key":"sshakirflhosp@gmail.com","avatar":null},"body":"Dear Git Community:\nMy organization is exploring using Git to manage our code repository.\nWe also have a strong need for documentation of our code.  The code is\nwritten in a proprietary language (Discern Explorer/CCL).  We looked\ninto Natural Docs but don't think we can combine it with Git.  Does\nanyone know of an app where we can combine the power of Git and code\ndocumentation in one?  Thank you. -Sultan\n"},{"id":"147551","messageId":"AANLkTi=pk4oXz84kWbHEzTUiWkTV5P4P9mTwzQbJG865@mail.gmail.com","threadId":"24684","inReplyTo":"AANLkTi=P=RsToSor=giC+dgV24bPj7KJ3eRV1M5a+iuD@mail.gmail.com","subject":"Re: Git and Documentation","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2010-08-09T20:43:41Z","receivedAt":"2010-08-09T20:43:41Z","isPatch":false,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"On Mon, Aug 9, 2010 at 17:35, Sultan Shakir wrote:\n> Dear Git Community:\n> My organization is exploring using Git to manage our code repository.\n> We also have a strong need for documentation of our code.  The code is\n> written in a proprietary language (Discern Explorer/CCL).  We looked\n> into Natural Docs but don't think we can combine it with Git.  Does\n> anyone know of an app where we can combine the power of Git and code\n> documentation in one?  Thank you. -Sultan\n\nCan you be clearer. That question makes little sense.\n\nYou can keep your documentation *in* Git if it's in files that you can\nkeep in version control. So in that case you could keep it alongside\nyour code.\n\nCan't you use this approach?\n"},{"id":"147681","messageId":"AANLkTikwVfymGB8oEQUN=1LMWoif22p316mm=PzSxQwa@mail.gmail.com","threadId":"24684","inReplyTo":"AANLkTi=pk4oXz84kWbHEzTUiWkTV5P4P9mTwzQbJG865@mail.gmail.com","subject":"Re: Git and Documentation","fromName":"Sultan Shakir","fromEmail":"sshakirflhosp@gmail.com","sentAt":"2010-08-10T19:55:10Z","receivedAt":"2010-08-10T19:55:10Z","isPatch":false,"sender":{"key":"sshakirflhosp@gmail.com","avatar":null},"body":"Yes I guess I could.  I am a little new at this.   I got the same idea\nafter watching Stephen Wood's video here:\nhttp://developer.yahoo.com/yui/theater/video.php?v=woods-yuiconf2009-yuidoc\n.  He had 3 rules/guidelines that might work if we use YUI Doc to\ngenerate the documentation:\n\n1) Generate documentation as part of the build\n2) Don’t manually check documentation in to VCS (do it automatically)\n3) Treat documentation comments like code\n\nI am not sure how to make it run as part of my build process though.\n\nOn Mon, Aug 9, 2010 at 4:43 PM, Ævar Arnfjörð Bjarmason\n wrote:\n> On Mon, Aug 9, 2010 at 17:35, Sultan Shakir wrote:\n>> Dear Git Community:\n>> My organization is exploring using Git to manage our code repository.\n>> We also have a strong need for documentation of our code.  The code is\n>> written in a proprietary language (Discern Explorer/CCL).  We looked\n>> into Natural Docs but don't think we can combine it with Git.  Does\n>> anyone know of an app where we can combine the power of Git and code\n>> documentation in one?  Thank you. -Sultan\n>\n> Can you be clearer. That question makes little sense.\n>\n> You can keep your documentation *in* Git if it's in files that you can\n> keep in version control. So in that case you could keep it alongside\n> your code.\n>\n> Can't you use this approach?\n>\n"},{"id":"147684","messageId":"4C61B737.50108@dbservice.com","threadId":"24684","inReplyTo":"AANLkTikwVfymGB8oEQUN=1LMWoif22p316mm=PzSxQwa@mail.gmail.com","subject":"Re: Git and Documentation","fromName":"Tomas Carnecky","fromEmail":"tom@dbservice.com","sentAt":"2010-08-10T20:31:51Z","receivedAt":"2010-08-10T20:31:51Z","isPatch":false,"sender":{"key":"tom@dbservice.com","avatar":"https://gravatar.com/avatar/900a300bdd1a8bbe086008ad78210bbee2ad2803b7d50a5cba04c1e9404bd6d2?d=mp&s=160"},"body":"On 8/10/10 9:55 PM, Sultan Shakir wrote:\n> Yes I guess I could. I am a little new at this. I got the same idea\n> after watching Stephen Wood's video here:\n> http://developer.yahoo.com/yui/theater/video.php?v=woods-yuiconf2009-yuidoc\n> . He had 3 rules/guidelines that might work if we use YUI Doc to\n> generate the documentation:\n> \n> 1) Generate documentation as part of the build\n> 2) Don’t manually check documentation in to VCS (do it automatically)\n> 3) Treat documentation comments like code\n> \n> I am not sure how to make it run as part of my build process though.\n\nPlease don't top post.\n\nIf the documentation is generated as part of the build, then there is no\nreason to have it part of the history - you can always rebuild it from\nthe source. For the same reason you don't put compiled source into git.\n\nAnd how to generate the doc as part of the build? That's up to you and\nvery much depends on what build system you use.\n\ntom\n"},{"id":"147685","messageId":"AANLkTimK_ounhk1Qou02V_3+JjpY9Y5ZO3OO2uRn6A7k@mail.gmail.com","threadId":"24684","inReplyTo":"4C61B737.50108@dbservice.com","subject":"Re: Git and Documentation","fromName":"Michael Witten","fromEmail":"mfwitten@gmail.com","sentAt":"2010-08-10T20:47:05Z","receivedAt":"2010-08-10T20:47:05Z","isPatch":false,"sender":{"key":"mfwitten@gmail.com","avatar":"https://avatars.githubusercontent.com/u/597101?v=4"},"body":"On Tue, Aug 10, 2010 at 15:31, Tomas Carnecky wrote:\n> If the documentation is generated as part of the build, then there is no\n> reason to have it part of the history - you can always rebuild it from\n> the source. For the same reason you don't put compiled source into git.\n\nWell, theoretically.\n\nAccording to:\n\n http://git.kernel.org/?p=git/git.git;a=blob_plain;f=MaintNotes;hb=todo\n\nthe git project's repository itself tracks generated documentation for\npractical reasons:\n\n The \"html\" and \"man\" [branches] are\n autogenerated documentation from the\n tip of the \"master\" branch; the tip\n of \"html\" is extracted to be visible\n at kernel.org at:\n\n http://www.kernel.org/pub/software/scm/git/docs/\n"},{"id":"147687","messageId":"AANLkTikK6_MqPQSg944DNfVULT3ccN9xMsObCAqHqxY_@mail.gmail.com","threadId":"24684","inReplyTo":"AANLkTimK_ounhk1Qou02V_3+JjpY9Y5ZO3OO2uRn6A7k@mail.gmail.com","subject":"Re: Git and Documentation","fromName":"Michael Witten","fromEmail":"mfwitten@gmail.com","sentAt":"2010-08-10T20:56:57Z","receivedAt":"2010-08-10T20:56:57Z","isPatch":false,"sender":{"key":"mfwitten@gmail.com","avatar":"https://avatars.githubusercontent.com/u/597101?v=4"},"body":"On Tue, Aug 10, 2010 at 15:47, Michael Witten wrote:\n> On Tue, Aug 10, 2010 at 15:31, Tomas Carnecky wrote:\n>> If the documentation is generated as part of the build, then there is no\n>> reason to have it part of the history - you can always rebuild it from\n>> the source. For the same reason you don't put compiled source into git.\n>\n> Well, theoretically.\n>\n> According to:\n>\n>  http://git.kernel.org/?p=git/git.git;a=blob_plain;f=MaintNotes;hb=todo\n>\n> the git project's repository itself tracks generated documentation for\n> practical reasons:\n>\n>  The \"html\" and \"man\" [branches] are\n>  autogenerated documentation from the\n>  tip of the \"master\" branch; the tip\n>  of \"html\" is extracted to be visible\n>  at kernel.org at:\n>\n>    http://www.kernel.org/pub/software/scm/git/docs/\n>\n\nI should add that generating documentation is time consuming and often\nrequires brittle software; there's a lot to gain by having one system\nproduce the same output for virtually everyone else.\n"},{"id":"147794","messageId":"AANLkTinyHAkr7bd6Wsr-=MtxN1QT1r8tRCGJ94vhpBHP@mail.gmail.com","threadId":"24684","inReplyTo":"AANLkTikK6_MqPQSg944DNfVULT3ccN9xMsObCAqHqxY_@mail.gmail.com","subject":"Re: Git and Documentation","fromName":"Sultan Shakir","fromEmail":"sshakirflhosp@gmail.com","sentAt":"2010-08-11T16:34:20Z","receivedAt":"2010-08-11T16:34:20Z","isPatch":false,"sender":{"key":"sshakirflhosp@gmail.com","avatar":null},"body":"On Tue, Aug 10, 2010 at 4:56 PM, Michael Witten wrote:\n> On Tue, Aug 10, 2010 at 15:47, Michael Witten wrote:\n>> On Tue, Aug 10, 2010 at 15:31, Tomas Carnecky wrote:\n>>> If the documentation is generated as part of the build, then there is no\n>>> reason to have it part of the history - you can always rebuild it from\n>>> the source. For the same reason you don't put compiled source into git.\n>>\n>> Well, theoretically.\n>>\n>> According to:\n>>\n>>  http://git.kernel.org/?p=git/git.git;a=blob_plain;f=MaintNotes;hb=todo\n>>\n>> the git project's repository itself tracks generated documentation for\n>> practical reasons:\n>>\n>>  The \"html\" and \"man\" [branches] are\n>>  autogenerated documentation from the\n>>  tip of the \"master\" branch; the tip\n>>  of \"html\" is extracted to be visible\n>>  at kernel.org at:\n>>\n>>    http://www.kernel.org/pub/software/scm/git/docs/\n>>\n>\n> I should add that generating documentation is time consuming and often\n> requires brittle software; there's a lot to gain by having one system\n> produce the same output for virtually everyone else.\n>\n\nThank you all.\n"}]}