[Gnumed-devel] Re: GNUmed manual

[Gour]

>>>>> "Karsten" == Karsten Hilbert <address@hidden> writes:

Karsten> No. But I know that a Wiki has only two dependancies: a working
Karsten> browser and a working internet connection.

Ahh...again we are comparing apples & oranges :-)

I was thinking about server-side deps.

For writing reST, one does not need even Internet connection - can write
down and apply later ;)


Karsten> I do understand that you are not talking about the entire wiki
Karsten> but only the manual as such.

>> The thing which you speak about we may call tips & tricks
Karsten> Not only. I am often updating the manual during night shift.

Heh, then you can write down reST in any nano-like editor and commit.


For James (& Karsten, if he desires so): Please take a look at some reST
example pages: http://svn.python.org/projects/doctools/trunk/doc/

This is sphinx - documentation generator used for official Python docs.

Please, tell me if it is possible for you to write GNUmed docs for fine
manual in that markup - here is http://sphinx.pocoo.org/rest.html rst
primer. 

If you are enthusiastic, then we can start working on it.

For the beginning, I am humbly asking you to work on the manual's
outline (being in Haskell, I'm top-bottom guy) and write it down - based
on current wiki docs.

Then, I'll convert it to reST and prepare for sphinx generation.

Karsten - see http://svn.python.org/projects/doctools/trunk/doc/Makefile

We can have cron job on the server to automatically invoke sphinx and
generate up-to-date docs (including Karsten's night-shift-notes) in HTML
as well as printable/offline PDF with a button to download it.

James, it would be nice to become familiar with basics of bzr (ask if
you need help) - it has simple model and GUI tools available, so no need
for command line ;)

In that way, we can put our manual in bzr branch.

If using bzr is too much for you, then you can just send me via email
your contributions and I'll push them to the server.

Does it sound OK with you?


I use Emacs which has nice syntax highlighting, but dunno which editor
you use on Mac. Maybe there is some support for it.

Karsten> Of course I have an editor available. Let's assume the manual
Karsten> is reST in VCS. 

Good, good.


Karsten> What do you propose the workflow to be like ?  Here's what
Karsten> needs to be done:


Karsten> - getting the latest version from VCS 

This is even not required 'cause it's possible to merge later, or,
update before committing to check if there are conflicts.

However, with < 10 Joe Users, it's low probability to get a conflict :-D

Karsten> - editing - 

I'm sorry, but this step you cannot avoid :-)

Karsten> compiling to check whether it is well-formed and looks OK -

No need for any compile.

btw, reST so simple and readable.

Karsten> checking in - 

If you have ability to check in - OK, although good practice with DVCS
is to have more eyes commit to the central server.

Karsten> generating at least HTML - upload to the "manual url"

My reply is that I do not believe that any change you make during your
night-shift is so urgent that it must be committed at once to the
server.

Karsten> How do I do that if all I have is a Windows machine with
Karsten> Notepad ?  And no, I can certainly not install anything on that
Karsten> machine.

My recommendation is to just write down in Notepad and, if you like,
commit plan reST to the server, if you REALLY need it.

Karsten> Compare with a Wiki:

Karsten> - surf to page - edit - preview - save

Sure, easy but this has a price.

Karsten> Nevertheless, a better manual is surely something desirable !

Nice that you agree.

>> We can help doing it, but some of those things require that you
>> modify your workflow a bit as well.

Karsten> You call the above "a bit" ?

Yes, just relax your temptation that your night-shift-notes must appear
immediately on the server.

If the docs requires that your night-shift-notes must be applied on the
spot to be usable, then I am suspicious that something is very bad with
the application and/or docs itself ;)

Karsten> Regarding collecting bug reports at Launchpad there is no need
Karsten> for consensus. Just do it and if it works better than what we
Karsten> have - great.

That's clear now - we won't discuss it any longer.

Karsten> Why of course will someone close fixed bugs. But being able to
Karsten> close bugs in a tracker isn't exactly the point of using a
Karsten> tracker, right ?

Sure. But having them in the tracker enables one to know what is going
on with the project. At the moment, I think you're the only one knowing
what's happening.

Karsten> Sure, because it enables me to contribute 7 days and nights of
Karsten> the week rather than 2 or 3.

The problem is that you consider that you contribute only if you apply
your changes immediately. By such thinking you won't not be able to move
to any DCVS where the workflow is different.

Work on docs 7 days and nights, commit locally and then once in a week,
push & merge to the main server.

Other doc-team members or coders are supposed to do the same - work on
certain parts of documentation of features/bugs and when they are ready
they push & merge.

I never really went into CVS-workflow, but can understand problem with
central-repo-thinking.

Karsten> Sure, if it proves that it is easily and completely syncable,
Karsten> for example. Some people may prefer to check out bzr rather
Karsten> than CVS. It'd be the same code, after all.

bzr branch of GNUmed at LP is regularly updated, but the problem is that
if I apply changes there and publish that branch, I wonder how easy will
you merge back to CVS.

These days, CVS is mostly used for one-time-import only to some more
capable DVCS, not for the keeping trunks in sync.

Moreover, having e.g. bzr branches of GNUmed, each dev-team member can
easily publish their own branches and it's easy to try out what other
devs are doing without any need for the merge.

I agree, it's a different way of thinking, but I humbly ask you to
consider it for the sake of overall GNUmed improvement.

Karsten> No. But you didn't act on any. (Except now for starting to act
Karsten> on the bug tracking issue - which is great.)

Let it be as you say, although I consider doing research to investigate
possible alternatives is also concrete work which, at least, takes time
like writing the code or documentation....but I won't take any credit
for it.


Sincerely,
Gour

-- 

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

pgp3FIVJlQkN9.pgp
Description: PGP signature