[Doc-SIG] proposal: a process for solving the Python Documentation Problem

[Laura Creighton]

In a message of Sat, 31 Dec 2005 00:19:35 EST, Chad Whitacre writes:
>Dear All,
>
>Here is an attempt to outline a process by which we might clarify and 
>solve the "Python Documentation Problem." The attempt here is to work 
>from the outside in, starting with the end result we want to see, and 
>working backwards from there to find the best solution.
>
>
>0. Agree on a problem-solving process. :^)

This is a great step 0.  Alas, I think things will all fall apart here.
My problem with your solution is that it is a technical solution
to a technical problem.  I think our problem is a social problem
and needs a social solution.

>1. Decide what documentation is in scope: Library Reference only?
>    Language Reference as well? Everything?

Everything, especially since people will want to use it for their own
documentation purposes.

>2. Brainstorm the end-user formats we might possibly want to read
>    documentation in: HTML, PDF, plain text, etc.

I don't think this is priority at all.  People who already like
one format or another already write tools to convert one to another.

And here we cut to a deep philosophical difference.  When you look at
documents, it matters a great deal whether you think that the control
of how it should be presented should lie with the _readers_ or with
the _writers_.  Commercial pressure has forced a current outcome where
the _writers_ more or less get to say what the readers get to read.
This leads to the situation where the _logical information about the
stucture of the document_ is mixed up in some sort of stew with the
_rendering information about how to print it on your rendering device_.

And some people think this is all well and good because the rendering
information is important information that belongs with the document.
Other people, including myself, think that this is pure evil because
the rendering information should exist with the readers, not with
the writers.  (Of course they should be free to send out their suggested
format).  So depending on where you sit on this philosophical devide, 
you will soon end up wanting either:

A _really low level markup language_ which allows you lots and lots
of control over how to render stuff, 

or

A _really high level document parser_ which can take any plain text
file, one that has no markup at all, and can conclude what its 
structure is, leaving you free to render that however you like.

So people go off and do this and they end up in different sorts of
messes.  The low level language people end up with text that can only
be read or understood _rendered_.  Often it is hard to search.  And
you often destroy the logical structure that people use when thinking
about documents.  You cannot search for the third paragraph, but only
the fifth line break, which becomes the fourteenth when paragraph
two gets a list inserted. Eventually you need some sort of authoring
tool to create text, because you just cannot read the markup-gloop
any more.

The document parser people find that there are some times when plain
text is not enough, and you really need to include some markup somewhere.
If they stick it in the document, they have started down the road where
they make their input text easier to parse.  You can end up with
markup-gloop this way too, even if it is only structural markup you
are inserting.  If you stick it in a companion document, then the
two get out of sync, and somebody always loses one.

>3. Prioritize formats.
>
>4. Crop the list to three or fewer primary target formats.
>
>5. Define the information that needs to be encoded to support the given
>    formats.
>
>6. Identify the storage format that best balances ease of migration,
>    maintenance, and authoring with adequacy to the task of encoding and
>    making accessible the necessary information.

I don't think we are ever going to agree on this one.

>7. Build, borrow, or buy the tools to migrate, maintain, author, access,
>    and transform the information.
>
>8. Migrate, maintain, author, access, and transform the information.
>
>
>chad

And here we are already at disagreements because I think you are 
solving a different problem than the one that is causing our problem.
I think that Fredrik Lundh just did this as well, so you are in good
company.

Now I need to go out and see the fireworks.  Then it is time to
cook the already-prepared New Years Dinner.  Which means I will be
too drunk later to consider writing my steps of solution to our
documentation problem, which I perceive differently.  We will have
the same step 0 ... and none of the rest.

But thank you for writing, and Gott Nytt År to all of you.

Laura