Loading ...
Sorry, an error occurred while loading the content.

Re: Should documentation be under source control?

Expand Messages
  • Tom
    ... RTF is a good choice - any text markup format is diffable.
    Message 1 of 16 , Apr 30, 2010
    • 0 Attachment
      --- In extremeprogramming@yahoogroups.com, Bill Caputo <list-subscriber@...> wrote:

      > 2) Documents should be stored in a diff'able format if at all possible
      > (i.e. MS Word and other binary document formats make horrible
      > artifacts)

      RTF is a good choice - any text markup format is diffable.
    • Andrea Francia
      ... My preferred format is reStructuredText where doc sources are readable as a plain text file but you can generate HTML, and PDF output. With specific tool
      Message 2 of 16 , May 1, 2010
      • 0 Attachment
        On Sat, May 1, 2010 at 1:15 AM, Tom <rossentj@...> wrote:

        > --- In extremeprogramming@yahoogroups.com, Bill Caputo <list-subscriber@...>
        > wrote:
        >
        > > 2) Documents should be stored in a diff'able format if at all possible
        > > (i.e. MS Word and other binary document formats make horrible
        > > artifacts)
        >
        > RTF is a good choice - any text markup format is diffable.
        >

        My preferred format is reStructuredText where doc sources are readable as a
        plain text file but you can generate HTML, and PDF output.

        With specific tool also MS Word is also diff'able, for example in
        TortoiseSVN you can easily compare word files.

        --
        Andrea Francia


        [Non-text portions of this message have been removed]
      • Jared Jones
        It can also be great (and fun) to write documentation in wiki pages and store that content on the code control server. this makes the docs easily changed and
        Message 3 of 16 , May 3, 2010
        • 0 Attachment
          It can also be great (and fun) to write documentation in wiki pages and store that content on the code control server. this makes the docs easily changed and become true "living documents". Fitnesse tests are a prime example that we use.




          [Non-text portions of this message have been removed]
        • Tim Ottinger
          I dunno. IMHO, wikis are great for a while, but soon fall into disuse. I guess we need a more group-bloggy way to do things. I don t know whether it s the wiki
          Message 4 of 16 , May 3, 2010
          • 0 Attachment
            I dunno. IMHO, wikis are great for a while, but soon fall into disuse.
            I guess we need a more group-bloggy way to do things. I don't know whether
            it's the wiki syntax or what.



            Tim Ottinger
            http://agileinaflash.blogspot.com/
            http://agileotter.blogspot.com/



            ----- Original Message ----
            > From: Jared Jones <jaredmjonessr@...>
            > To: extremeprogramming@yahoogroups.com
            > Sent: Mon, May 3, 2010 2:16:06 PM
            > Subject: [XP] Re: Should documentation be under source control?
            >
            > It can also be great (and fun) to write documentation in wiki pages and store
            > that content on the code control server. this makes the docs easily changed and
            > become true "living documents". Fitnesse tests are a prime example that we
            > use.




            [Non-text portions of this message
            > have been removed]



            ------------------------------------

            To
            > Post a message, send it to:
            > ymailto="mailto:extremeprogramming@..."
            > href="mailto:extremeprogramming@...">extremeprogramming@...

            To
            > Unsubscribe, send a blank message to:
            > ymailto="mailto:extremeprogramming-unsubscribe@..."
            > href="mailto:extremeprogramming-unsubscribe@...">extremeprogramming-unsubscribe@...

            ad-free
            > courtesy of objectmentor.comYahoo! Groups Links

            > http://groups.yahoo.com/group/extremeprogramming/


            > http://groups.yahoo.com/group/extremeprogramming/join
            (Yahoo!
            > ID required)

            > href="mailto:extremeprogramming-digest@yahoogroups.com">extremeprogramming-digest@yahoogroups.com
            >

            > ymailto="mailto:extremeprogramming-fullfeatured@yahoogroups.com"
            > href="mailto:extremeprogramming-fullfeatured@yahoogroups.com">extremeprogramming-fullfeatured@yahoogroups.com

            > ymailto="mailto:extremeprogramming-unsubscribe@yahoogroups.com"
            > href="mailto:extremeprogramming-unsubscribe@yahoogroups.com">extremeprogramming-unsubscribe@yahoogroups.com

            > http://docs.yahoo.com/info/terms/
          • JeffGrigg
            A successful Wiki seems to require a critical mass of active users. It seems to work if you make it a regular part of your defined process, so that people
            Message 5 of 16 , May 4, 2010
            • 0 Attachment
              A successful Wiki seems to require a critical mass of active users. It seems to work if you make it a regular part of your defined process, so that people will get into the habit of looking there. And you need at least a few people who work hard to ensure that useful and up-to-date content is put on the Wiki.

              When everyone seems to be hoping that someone else will update the Wiki content, it will probably fall out of date. "People need to realize... When you see something wrong on the Wiki, fix it. Yes, you can. Just go ahead and fix it. You don't need to hold meetings to discuss it, start a project on it, and to get blessed with official authority. When you see a problem, just fix it. You're empowered. Honest, you are."


              --- Tim Ottinger <linux_tim@...> wrote:
              > I dunno. IMHO, wikis are great for a while, but soon fall
              > into disuse. I guess we need a more group-bloggy way to
              > do things. I don't know whether it's the wiki syntax or what.
            • scott preece
              We use wikis a lot for documentation, but we ve found it a real pain to work around the lack of a cross-page versioning mechanism. That is, while you can
              Message 6 of 16 , May 4, 2010
              • 0 Attachment
                We use wikis a lot for documentation, but we've found it a real pain to work around the lack of a cross-page versioning mechanism. That is, while you can usually refer to a specific version of a page, there's no way to freeze a consistent set of page versions, so people following a link from page to page will end up at the correct version of the linked page.

                We do this the clunky way - just produce version-specific pages with links to version-specific pages - but we aren't really happy with it.

                scott


                --- In extremeprogramming@yahoogroups.com, Jared Jones <jaredmjonessr@...> wrote:
                >
                > It can also be great (and fun) to write documentation in wiki pages and store that content on the code control server. this makes the docs easily changed and become true "living documents". Fitnesse tests are a prime example that we use.
                >
                >
                >
                >
                > [Non-text portions of this message have been removed]
                >
              • Olof Bjarnason
                2010/5/4 JeffGrigg ... Wikis require a certain kind of people - those who like writing tags & stuff. Usually developer-minded people.
                Message 7 of 16 , May 5, 2010
                • 0 Attachment
                  2010/5/4 JeffGrigg <jeffgrigg@...>

                  >
                  >
                  > A successful Wiki seems to require a critical mass of active users. It
                  > seems to work if you make it a regular part of your defined process, so that
                  > people will get into the habit of looking there. And you need at least a few
                  > people who work hard to ensure that useful and up-to-date content is put on
                  > the Wiki.
                  >
                  > When everyone seems to be hoping that someone else will update the Wiki
                  > content, it will probably fall out of date. "People need to realize... When
                  > you see something wrong on the Wiki, fix it. Yes, you can. Just go ahead and
                  > fix it. You don't need to hold meetings to discuss it, start a project on
                  > it, and to get blessed with official authority. When you see a problem, just
                  > fix it. You're empowered. Honest, you are."
                  >

                  Wikis require a certain kind of people - those who like writing tags &
                  stuff. Usually developer-minded people.

                  If anyone with less-than-exact writing language is involved, something like
                  Etherpad might work better:

                  http://typewith.me/
                  (typewith.me is one of several Etherpad-hosts)


                  >
                  > --- Tim Ottinger <linux_tim@...> wrote:
                  > > I dunno. IMHO, wikis are great for a while, but soon fall
                  > > into disuse. I guess we need a more group-bloggy way to
                  > > do things. I don't know whether it's the wiki syntax or what.
                  >
                  >
                  >



                  --
                  http://olofb.wordpress.com


                  [Non-text portions of this message have been removed]
                Your message has been successfully submitted and would be delivered to recipients shortly.