[Twisted-Python] Simpler twistedmatrix.com doc indexes
Hi there. I've been playing around with using lore and microdom to generate better indexes for the Twisted documentation, and also to move everything into a single /doc tree. The results, at least until I break it all again, are here: http://microdev.dyndns.org:8080/doc/ I'm looking for feedback on whether this is any easier to use, and what could be improved. There are some issues I already know about: - Links to non-html resources are broken - Core HOWTO list is gigantic and messy - "Other" docs are strangely laid out Thanks, Brendon
On Tue, May 17, 2005, Brendon Hogger wrote:
It looks good... but we don't actually really *have* a master doc index any more (yes http://twistedmatrix.com/documents still exists, but the docs there are 1.3). Do you suggest we restore it? -Mary
On Tue, May 17, 2005, Brendon Hogger wrote:
Can you file a bug at http://twistedmatrix.com/bugs/ about making these changes and assign it to me (hypatia) please, when you've finished experimenting? Source files appreciated, and thanks very much for your work on this. -Mary
Hi Brendon, I would suggest you make the main doc page much simpler. I'd like to see it focus on the core docs and perhaps provide some form of preferred or recommended learning path. If the intention is to help people new to Twisted I think we have to narrow the selection down so it don't become too overwhelming. At least my learning experience with Twisted was to take it a chunk at a time. Trying to grip the whole project is just too much to start with. I'm not saying your index is bad, just that it'd probably be good to add some intro page. /Simon -----Original Message----- From: twisted-python-bounces@twistedmatrix.com [mailto:twisted-python-bounces@twistedmatrix.com] On Behalf Of Brendon Hogger Sent: den 17 maj 2005 09:01 To: Twisted general discussion Subject: Re: [Twisted-Python] Simpler twistedmatrix.com doc indexes
Yes. I think it's much easier to get an idea of what's available when it's all collected together in one place. It seems fairly common to hear people say that Twisted is lacking documentation because they just don't stumble across it. - Brendon _______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
On Tue, May 17, 2005, Brendon Hogger wrote:
It looks good... but we don't actually really *have* a master doc index any more (yes http://twistedmatrix.com/documents still exists, but the docs there are 1.3). Do you suggest we restore it? -Mary
On Tue, May 17, 2005, Brendon Hogger wrote:
Can you file a bug at http://twistedmatrix.com/bugs/ about making these changes and assign it to me (hypatia) please, when you've finished experimenting? Source files appreciated, and thanks very much for your work on this. -Mary
Hi Brendon, I would suggest you make the main doc page much simpler. I'd like to see it focus on the core docs and perhaps provide some form of preferred or recommended learning path. If the intention is to help people new to Twisted I think we have to narrow the selection down so it don't become too overwhelming. At least my learning experience with Twisted was to take it a chunk at a time. Trying to grip the whole project is just too much to start with. I'm not saying your index is bad, just that it'd probably be good to add some intro page. /Simon -----Original Message----- From: twisted-python-bounces@twistedmatrix.com [mailto:twisted-python-bounces@twistedmatrix.com] On Behalf Of Brendon Hogger Sent: den 17 maj 2005 09:01 To: Twisted general discussion Subject: Re: [Twisted-Python] Simpler twistedmatrix.com doc indexes
Yes. I think it's much easier to get an idea of what's available when it's all collected together in one place. It seems fairly common to hear people say that Twisted is lacking documentation because they just don't stumble across it. - Brendon _______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
participants (3)
-
Brendon Hogger -
Mary Gardiner -
Simon