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

12316WSJT Documentation Migration Background

Expand Messages
  • Greg Beam
    Feb 7, 2014
    • 0 Attachment
      Hash: SHA1

      Hi Chuck, All,

      With the confusion surrounding the current documentation workflow, I
      thought I would provide a bit of background as to why things seem a
      bit chaotic at the moment.

      The decision to move from a Binary Method (MS Word, PDF, etc) to an
      Open Source (OS) text based method (AsciiDoc, XML, LaTeX, DocBook,
      etc) caught me off guard, and I've been playing catch-up. Normally,
      the back end process is in place before the shift happens and the
      authors are not caught up in the transition details.

      Traditionally, there are 4 to 5 activity types associated with open
      source documentation. Some projects have more, others less:

      Authors: Submit material for incorporation
      Editors: Submit + structure material for incorporation
      Translators: Translate to given languages
      Programers: Interface with VCS and provide build tools
      Designers: Work with CSS, HTML, Configs, Graphics
      Gatekeepers: Those controlling context integration

      Where one fits into these areas is a matter of choice coupled with
      abilities or a given desire to learn something new, which is a corner
      stones of the WSJT applications.

      In many OS programs, these areas are combined, one person may wear
      many hats. More often than not, this is due to resource availability.
      I was the one who brought the AsciiDoc idea to Joe, so I feel somewhat
      responsible for getting a working model put together and to ease the
      Author / Editor burden. This is taking me a bit of time to pull together.

      Over the last few days, there have been many changes, all of which
      impact Author / Editor activities. With the new document structure and
      minimalistic build process working, we can now focus on contribution
      workflows, for example:

      * Methods of contribution, how can one contribute?
      * What needs to be done (To-Do Lists), where do I get the list?
      * What tools are needed to "Build" v.s. "Contribute"
      * What format should submissions take, text, marked-up, what?
      * Where are the mark-up standards / definitions, how do I use them?
      * What the difference be contribution and building, how do they differ?
      * How can I commit directly to the source tree?
      * How to built & Test, Windows v.s. *Nix?

      Those are just a few of the things that need ironing. While we do not
      have a rigid road-map, the end goal is clear, provide the best
      documentation we can, given the current state of transition.

      Suffice it to say, there are bumps in the process (rough sketch at
      best I think) and I would not expect that to be smooth any time soon.

      That said, if Editing is not one's cup of tea, a simple text document
      sent to the development list could be an input channel. The Yahoo
      group pages are filled with things that could be converted over useful

      If you have additional questions, comments or ideas to make the
      transition smoother, by all means, share them with the group. I am
      sure Joe is always open to improvement ideas.

      Greg, KI7MT
      -----BEGIN PGP SIGNATURE-----
      Version: GnuPG v2.0.22 (MingW32)
      Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

      -----END PGP SIGNATURE-----