12316WSJT Documentation Migration Background
- Feb 7, 2014-----BEGIN PGP SIGNED MESSAGE-----
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.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.22 (MingW32)
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/
-----END PGP SIGNATURE-----