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 - Doc-SIG@python.org http://mail.python.org/mailman/listinfo/doc-sig
