[Gnumed-devel] Re: Wiki documentation separation

[Gour]

>>>>> "James" == James Busser <address@hidden> writes:

James> Some principles, and maybe early worthwhile resolutions: - there
James> are important differences between "reference" documentation and
James> "in order to best understand and learn to be able to use" kinds
James> of documentation

Right.

James> - the wiki will always remain useful as a pointer... "where do I
James> find what I need (including manuals and other documentation)"
James> even when the latter were not *constructed* on the wiki

True - just short notes and links to real docs.

James> - at minimum, we likely want available documentation
James> (downloadable) linked *from* the wiki; not yet determined is
James> whether the wiki would be the primary site from which the
James> documents are identified and organized, or whether the wiki would
James> point to something external that has its own mechanism for
James> organizing and offering what is available.  

There are two possibilities:

a) writing docs online in e.g wiki as now and

b) writing docs offline as I suggested

Don't think about:

c) writing docs online & offline

because it brings extra & tedious work of converting & syncing and tools
are less than perfect. (I'd be ready to convert the present wiki only as
one-time-affair.)


Moreover, as already written several times: docs has to be kept under
VCS to get all the benefits of it as well as preventing any JoeUser to
commit.

James> - we may also want any existing versions to be published even
James> while they are incomplete... it would only need to be clear when
James> these are at a level of draft, and ultimately they would get
James> frozen with a GNUmed release and, once frozen, would only be
James> fixed for errata.

See, this consideration applies only when you don't have docs under VCS
because otherwise, the online or released version is the one which is
*at the moment* committed to the main trunk.

Drafts & similar stuff may live in the private or 'experimental'
branches of other doc-team members until they evolve from draft into
committed status.

James> - we will also want feedback. If we imagine that each document
James> may be in chapters, 

What do you think when you say: "each document may be in chapters" ?

The User Manual would certainly have lot of chapters...

James> can we consider whether to publish from reST into the (sub) wiki
James> and use wiki editing as a basis to do a diff between the base
James> version and the suggested changes, from which the doc team would
James> pick and choose as appropriate?

Huh, you lost me here...

I clearly see that you are not ready to give up wiki editing and
therefore better to stop dreaming & inventing strange work-flows in order
not to 'lose' wiki.

Until you don't understand that the natural place for application's
documentation is in the same place as application's code and to be kept
under VCS, there is no possibility to really re-organize things 'cause
for that paradigm-shift is required.

Well, I really consider that it's time to close this
documentation-talk. It takes so much energy & time (at least here) and I
understood that the time is not ready for it now.

As I wrote earlier, you're free to suggest whatever you desire, but I
won't tax my brain with it any longer...

I'm awaiting first devel-bugs to arrive to put LP's bug tracker to full
use and there will be (possibly) some opportunity to help with
translation, convert shell scripts to Python, some fix/patch here &
there....


Sincerely,
Gour


-- 

Gour  | Zagreb, Croatia  | GPG key: C6E7162D
----------------------------------------------------------------

pgpsra0PoON7F.pgp
Description: PGP signature