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 - [email protected]
http://mail.python.org/mailman/listinfo/doc-sig
