[Doc-SIG] 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