proposal: a process for solving the Python Documentation Problem

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

proposal: a process for solving the Python Documentation Problem

Chad Whitacre
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. :^)

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

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

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.

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

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: 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


_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: proposal: a process for solving the Python Documentation Problem

Chad Whitacre
Laura,

Thanks for giving me an opportunity to clarify my proposal.

I more or less agree with you that mixing "logical" and "rendering"
information is "pure evil." However, the real world use case for this
documentation is that it end up in several rendered formats. My
suggestion is that explicitly identifying the most important rendered
formats will help flush out the true requirements for the base (i.e.,
"logical" or semantic) format.

On the other hand, I confess that I don't follow your suggestion that
separation of "logical" and "rendered" information leads to a plain text
base format, one without any markup. Why exclude markup that is semantic
rather than presentational?

Also, you hint that it might be helpful to define the problem itself
more clearly, and I agree. The problem I want to see solved is
Fredrik's: how do we cut the documentation workflow cycle down from 3-6
months to, say, 3-6 days?




chad

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: proposal: a process for solving the Python Documentation Problem

janssen-3
In reply to this post by Laura Creighton
> 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.

Some of the original document formats developed at PARC in the 70's
for use on the Alto and Dorado computers used plain text plus markup.
There was a plain-text body, followed by a zero octet (or perhaps two,
I don't remember), followed by a binary section that included the
markup.  Most text processors of the time would simply trim off the
binary section when presenting the document, so what you saw in a text
editor was just the plain text.  WYSIWYG document editors, however,
would also read the markup and interpret it appropriately for editing
purposes.  The two didn't get out-of-sync because they were in the
same file.

Bill
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: proposal: a process for solving the Python Documentation Problem

Fredrik Lundh
In reply to this post by Chad Whitacre
Chad Whitacre wrote:

> 0. Agree on a problem-solving process. :^)

I'll check back in 2020 ;-)

In the meantime, using a small number of 15-minute slots, I'll implement
a first draft of a pythondoc/edit-through-the-web solution for a wider
audience.

An outline follows:

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

Library reference plus relevant portions of the language reference.

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

HTML (in this iteration).

> 3. Prioritize formats.

Done.

> 4. Crop the list to three or fewer primary target formats.

Done.

> 5. Define the information that needs to be encoded to support the given
>     formats.

Done.

> 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.

Done ;-)

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

In progress.  I'll let you all know when there's something to play with.

</F>



_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig