Re: Project documentation format (fwd)

From: Alan Dechert <adechert_at_earthlink_dot_net>
Date: Fri Aug 01 2003 - 10:12:17 CDT

Van has taken on the task of producing the Requirements and Specification.
Ed is professional technical writer and will be helping Van. Before
deciding on this, I suggest that we get some input from them. Van reported
that he will be out of commission for a few days, so maybe we can decide on
this next week. BTW, I don't think anyone mentioned HTML as an alternative.
Does APT handle pagination okay?

Alan

- ----- Original Message -----
From: "David Mertz, Ph_dot_D_dot_" <voting-project_at_gnosis_dot_cx>
To: <voting-project@lists.sonic.net>
Sent: Friday, August 01, 2003 12:08 AM
Subject: Project documentation format (fwd)
Message-ID: <9460@initial.digest>

> Telephone Conference
>
> I was fortunate enough to be able to participate, by telephone, in
> today's meeting with Alan Dechert, Arthur Keller and Adrianne Yu Wang
> (unfortunately with a bad connection; I leave it to Alan and Adrianne
> to summarize the meeting).
>
> * Documentation formats
>
> One minor administrative issue was raised that I would like to comment
> on, and make a proposal for going forward. We discussed the need to
> develop a variety of documentation associated with the project. I
> expressed a concern to avoid the proprietary MS-Word as a format--if
> for no other reason than it excludes me (and any other users of open
> source OSs) from participating in the documentation process. Beyond
> its proprietary nature, MS-Word does not play nice with versioning and
> collaboration systems like CVS on Sourceforge (although I am aware it
> has its own versioning tools, to an extent).
>
> * Finding simplicity
>
> Arthur suggested <<LaTeX>> as an open alternative, which indeed it is.
> But on reflection, I believe the learning curve for <<LaTeX>> is
> excessive for documentation contributors who may not themselves be
> programmers.
>
> I believe a good alternative is to adopt <APT> (Almost Plain Text) as
> an intermediate documentation format. This allows export to targets
> such as:
>
> * RTF
> * LaTeX
> * DocBook
> * PDF/PS
> * HTML
>
> In case you haven't figured it out by now, this note is written using
> somewhat contrived <APT> formatting. You can read all the details at
> {{{http://www.xmlmind.com/aptconvert.html}The aptconvert homepage}}.
> <aptconvert> is the Java-based conversion tool to add markup to <APT>.
>
> * Versioning and output friendliness
>
> I wrote my book <Text Processing in Python> using my own conceptually
> similar format that I call "smart ASCII." However, when
> Addison-Wesley asked me to help convert someone else's book that was
> created in a custom XML format, I did some research into similar tools
> that had a more flexible range of targets. Python programmers will be
> familiar with reStructuredText--but I find it both just a bit too
> complicated for novices, and a bit too Python specific. I arrived at
> <APT> as the best such format (at least for my purpose then).
>
> The nice thing about these formats is that they make running a context
> diff between document versions REALLY easy. And they play nice with
> CVS. And the look quite a lot like what people normally send in
> uncluttered email (with occassional minor variations). With <APT>,
> you can even include verbatim code like:
>
> +-------------------------------------------+
> #!/usr/bin/env python
> from gnosis.xml.objectify import make_instance
> doc = make_instance('document.xml')
> +-------------------------------------------+
>
> But really what the benefit amounts to is that the document
> maintainer(s) can take a plain ASCII writeup that a non-technical user
> writes, and with only minimal effort, add a little indentation and
> emphasis to make it good APT. From there, we can regularly publish
> nice looking RTF, HTML or PDF versions of the same content on our
> Sourceforge project "Docs" section.
>
> I would be very happy to take responsibility for the markup and export
> of such contributed documentation, if the group agrees this is a good
> way to go. I imagine I will also contribute to the actual writing of
> some of the documentation, but a commitment to such minor
> documentation massaging is a much smaller one than is one to writing
> it.
>
> Yours, David...
Received on Fri, 1 Aug 2003 08:12:17 -0700

This archive was generated by hypermail 2.1.8 : Wed Aug 06 2003 - 12:50:26 CDT