Hi Joe, All, Thank you for the comments on the documentation examples I submitted. It should be noted, the docs were merely an example, and require a fare amount of work before being considered release quality, especially the build script and chapter management options. The script is noting more than a quick build tool to see errors and prevent allot of typing :-). I fully intended to re-write it for a larger audience.
If the goal is to create a Distributed + Gatekeeper model for
documentation, I think it is wise to iron out a few things beforehand,
which could prevent allot of rework in the future. The following items
are from my notes when I was thinking of implementation, irrespective of
Asciidoc being used as the markup language. I can assist in setting up
and working the model if desired, with he exception of translation.
Please feel free to send feedback / recommendations for improvement.
These are just a few items I think are important for any documentation
project.
Thoughts / Ideas / Questions:
** Workflow && Repository Management
- Assuming SVN is the vcs of choice, should the documentation reside
within the project branch (e.g. ../wsjt/trunk/wsjtx/docs), or be at the
trunk level (e.g. /wsjt/trunk/wsjt-docs/{wsjt,wsjtx,wspx,wsprx,map65})
etc.?
I think keeping the docs at the trunk level, mirroring the project
branch layout, allows the most flexibility for contributors &&
commiters, both in web-publishing (if desired) and application
packaging. This aids in maintaining the same style across all projects
(WPSR, WSPRX, WSJT, WSJTX, MAP65, etc), creates a central build process
(build one or all of them), and makes merge proposals / commit requests
easier for the contributor, reviewer and/or commiter.
** Change Management && Task Tracking
- With a small number of contributors, centralized development can be
worked out between the writers themselves (who is working on what page,
chapter, new feature, typo's etc). As the project grows, and becomes
more distributed in nature, preventing overlap, and working To-Do-Lists
can get a bit messy. Somewhere in the wsjtx-devel archives was talk
about using the bug feature provided by BerliOS. I think using bugs for
writing and/or updating documentation is a good idea. A simple "Want to
Help Link" ==> points to the bug list, works for anyone wanting to
contribute. I've not used the BerliOS bug system extensively, but for
the most part, basic functionality is all that's required for
documentation.
** Style Guide
- We all have our own writing style, methods and tools. No matter which
markup language is used, providing examples of "How Do I", "What To Do",
"What Not To Do", "How to Setup the Docs environment" .. etc, is
important for both new contributors as well as the veterans. A little
work upfront can save new contributors allot of frustration.
** Translation
- The styles guide should address this in part, writing style, phrases,
localized slang or trendy wording .. etc, but I think it's important to
keep in mind how non-English speaking users can get help. We all want to
work Rare DX Right? :). The build process and writing style should make
an allowance for this. While the bulk of the work still falls to the
translator, the structure we use should assist them as much as possible.
We could talk all day about what is the best way forward. There are as
many ways to work documentation as there applications to use, but I
think having a process in place to start with, will get us going in the
right direction. If the process does not work, we can always change
it :)
73's
Greg, KI7MT
[email protected]
signature.asc
Description: This is a digitally signed message part
_______________________________________________ Wsjt-devel mailing list [email protected] https://lists.berlios.de/mailman/listinfo/wsjt-devel
