[Gnumed-devel] Re: small Sphinx demo

[Gour]

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

Sebastian> To sum up our dispute I understood it like this. Wiki is by
Sebastian> far the easiest (not the prettiest) way to edit something and
Sebastian> have it show up instantly without any other local tools.

Well, wiki is, imho, not suited for writing serious & structured
documentation. It's OK for quick and short notes, but not for technical
documentation like application's manuals etc. which require very god
structuring, index, glossaries, figures (screenshots), code snippets
etc.

IOW,  I consider that such documentation has to be written offline & kept
under VCS.

Sebastian> So some GNUmed members exclusively edit documentation in
Sebastian> environments where all they have is an internet browser. No
Sebastian> USB drive. No VCS . They could edit in notepad and email it
Sebastian> to themselves and later check it in but they do not want
Sebastian> that. 

That's the point: "they could...but they do not want.."

I'm proposing how to improve overall project by producing high-quality
documentation which is atm, without offense, with very good content but
very badly structured (no wonder when wiki is used) - e.g.  mixing
Developer Guide with the User Guide - these two do not belong to the
same 'manual', or

Client Maintenance --> Installation and Upgrade leading to

http://wiki.gnumed.de/bin/view/Gnumed/InstallerGuideHome page with some
parts belonging to the manual (general stuff) and some are just for
online site.

Of course, the part of the problem is that manual's content is
intertwined with the site's content, although the user-application
manual should be separated and available to be shipped with the released
tarball/packages and be invokable as 'internal' help.

So, if we want to make improvement it's very difficult to do if everyone
wants to stick with his workflow even though they're not examples of
'best practice'.

Sebastian> they want results on the screen by hitting the save button in
Sebastian> the wiki.


This is, imho, childish idea to get 'instant gratification' :-)

Besides that, real docs are not written by JoeUser submitting something
to the wiki.

If someone is serious to help with the documentation which is integral
part of any serious documentation, then one is supposed to be ready to
learn some of the project's technology like: VCS, programming language,
documentation tool-chain etc.

At least, if someone does not want to learn new technology, he/she can
always email some documentation contribution or patch to the
e.g. devel-list.

I'm not sure you are so easy accepting patches to the code (without much
quality control) as you are eager to allow JoeUser writing manual online
via wiki.

Moreover, I tend to think that docs is one of the weakest points in
GNUmed's wider adoption and by improving it devs will have to spend less
time on devel-list which leads to increased productivity of most
important factor.


Sebastian> For a to be printed manual your approach may be cleaner. 

Even for online docs.

Sebastian> Wiki --> edit over months until a release --> transfer manual
Sebastian> from wiki to rst and tidy up --> release manual and software.

No, this is just extra work and I simply do not agree (for a proposed
workflow) that JoeUser can write directly to wiki and 'Save the button'.

There should be doc-team consisting of experienced users who work
together (similar to dev-team), contribute to docs source files (kept
under VCS), discuss, plan...commit to the doc-tree which can be
automatically generated.

In other words, as Karsten & other dev do not allow CVS access to
JoeUser, I simply propose the same for documentation 'cause the docs are
part of the application same as the code and therefore should be treated
equally.

Those who show by their small contributions (sent e.g. via email
as doc-patches) that they understand and know how to work with GNUmed
can become members of the doc-team and commit to the doc-tree.

Even better, everything which goes to the doc-tree has to be approved by
at least one/two/... other members in order to keep quality.

The same quality control is, of course, desirable for the code as well.

DVCS helps here a lot enabling every {doc,dev} member of the team to
work on special parts of {docs,features} and things are committed "when
ready and approved".

I simply do not understand the 'rush' that every commit to doc should be
immediately available :-/


The nice-looking documentation can be automatically updated after every
successful commit to the doc-tree keeping the docs always up-to-date.

The current wiki site can be used for News, Download links, Dev info
etc.


So, to sum up: I do not propose reST markup to get nice printed manual
out of the wiki content only, but re-organization how to docs are
produced by moving all the docs from wiki to doc/ into the source tree
which is kept under VCS and to which the same rules apply as to the
contributing code.

Otherwise, there is no sense to put effort of transferring wiki content
to *.rst to get somewhat nicer-looking pdf manual.

I'm proposing to increase the quality by adopting a different
workflow...which is, as you remarked, possible but : "they
could...but they do not want.."


Sincerely,
Gour

-- 

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

pgphN2X_dONcP.pgp
Description: PGP signature