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

[XP] Re: Should documentation be under source control?

Expand Messages
  • 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 1 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 2 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 3 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 4 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 5 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.