Opened 3 years ago

Closed 3 years ago

#5427 enhancement closed fixed (fixed)

Improve core documentation index page

Reported by: itamar Owned by: itamar
Priority: normal Milestone:
Component: core Keywords: documentation
Cc: jesstess, thijs Branch: branches/howto-index-5427-2
(diff, github, buildbot, log)
Author: itamarst, itamar Launchpad Bug:

Description

The core howto documentation is badly organized, and could do with some descriptions and explanations.

Change History (15)

comment:1 Changed 3 years ago by itamarst

  • Author set to itamarst
  • Branch set to branches/howto-index-5427

(In [33312]) Branching to 'howto-index-5427'

comment:2 Changed 3 years ago by itamar

  • Author changed from itamarst to itamar
  • Keywords review added

comment:3 Changed 3 years ago by jesstess

  • Cc jesstess added
  • Owner set to jesstess

comment:4 Changed 3 years ago by jesstess

  • Keywords review removed
  • Owner changed from jesstess to itamar

Thanks for working on this, itamar. Your changes look good; feel free to deploy now if you want, but a few comments:

  • "Network programming should be easy... and fun!" It's hard for me to read this with a straight face.
  • Is "Test-driven development with Twisted" the third document new users should be reading, after servers and clients? Would the intro to Deferreds be better? Or perhaps TwistedQuotes, which is a short application example then followed by the longer Finger tutorial?
  • I'd prefer that the Legacy Documentation not be referenced in the index at all, rather than listed but saying it is broken. We can remove those links and open tickets to either reintroduce updated documentation or remove those documents altogether.

comment:5 Changed 3 years ago by itamar

  1. Is this a good thing or bad thing? I do want this to be entertaining.
  2. I think test-driven development should be pretty central, because that's one of the big wins with Twisted: the ability to test your network code. It's also good marketing for more experienced developers. Moreover, the testing tutorial only adds reactor.callLater to the knowledge from the previous two howtos, and repeats the explanations of factory/protocol etc., so I think it's a reasonable next step.
  3. Will do.

Another requirement before resubmitted for review: reorganize book.tex to match the new index.

comment:6 Changed 3 years ago by itamarst

  • Author changed from itamar to itamarst, itamar
  • Branch changed from branches/howto-index-5427 to branches/howto-index-5427-2

(In [33413]) Branching to 'howto-index-5427-2'

comment:7 Changed 3 years ago by itamar

  • Keywords review added
  • Owner itamar deleted

OK, I removed two bad howtos, moved telnet howto out of legacy since it can be salvaged (the functionality still exists in non-deprecated form in twisted.conch), updated book.tex (there were *lots* of missing howtos!).

Buildbot documentation slave is happy:
http://buildbot.twistedmatrix.com/builders/documentation/builds/1792

comment:8 Changed 3 years ago by jesstess

  • Owner set to jesstess

comment:9 Changed 3 years ago by exarkun

Thanks. Documentation tickets are super important, we need to keep doing stuff like this.

  1. The graphical overview doesn't strike me as particularly useful. Also, it's full of incorrect information. We have another ticket for updating it which people have been avoiding working on for ages. Should we take this opportunity to drop the "document"?
  2. It's true that conch provides telnet functionality, but it's not API compatible (at all) with twisted.protocols.telnet, deprecated since Twisted 2.1, which is what the telnet howto documents. We really just need a new howto for the conch telnet library.
  3. I am a little bit uneasy about all the new claims of "easy" things in the index. Good documentation shows you that things are easy, it doesn't tell you that they are. +1 on being entertaining, but claiming everything is easy here looks bad to me. It's one of the things that made deferredindepth.xhtml such a terrible document and worthy of deleting here.
  4. Here's some scope creep for you. The "low level" section of the index doesn't make a lot of sense to me. SSL, endpoints, and processes are low-level? Not really. SSL and processes are just features you might want, and inasmuch as we're talking about Twisted APIs here, these APIs are probably pretty high-level compared to what a reader is used to, or what they might find elsewhere. And on top of that, endpoints are the highest-level connection setup API Twisted has.

I don't have the tools to build the book on hand. I'll assume you've tested this yourself and it still works and looks proper. Please merge when you've addressed the above points to your satisfaction (unless jesstess has anything to add :). Thanks!

comment:10 Changed 3 years ago by jesstess

  • Keywords review removed
  • Owner changed from jesstess to itamar

comment:11 Changed 3 years ago by thijs

  • Cc thijs added

It also looks like there are example listings files that were referenced in the deleted core/howto/deferredindepth.xhtml that can now be deleted.

comment:12 Changed 3 years ago by thijs

\input{../specifications/banana.tex} was also removed from the book.tex for some reason.

comment:13 Changed 3 years ago by itamar

  • Keywords review added
  • Owner itamar deleted

Review comments have been addressed:

  1. Deleted overview and images, added 1712.misc for that ticket, #1712.
  2. Deleted telnet.
  3. Rewrote the bits about easiness.
  4. Renamed that sections to "Networking and Other Event Sources", and moved endpoints to high-level infrastructure.
  5. Deleted deferred in depth code listings.
  6. I removed banana spec on purpose - it's not on regular howto index, and I doubt people looking at book-like PDF actually want it either.
  7. I also made a few more minor edits, e.g. the tutorial section is now "Getting Started".

Buildbot for docs:
http://buildbot.twistedmatrix.com/builders/documentation/builds/1806

comment:14 Changed 3 years ago by jesstess

  • Keywords review removed
  • Owner set to itamar

This is a tremendous improvement over the existing index -- thanks for working on this. Please merge!

comment:15 Changed 3 years ago by itamarst

  • Resolution set to fixed
  • Status changed from new to closed

(In [33453]) Merge howto-index-5427-2.

Author: itamar
Review: jesstess, exarkun, thijs
Fixes: #5427, #1712

The core howto index has had many crufty howtos removed, and has been reorganized. Also, the generated PDF should now contain all howtos (it was missing some).

Note: See TracTickets for help on using tickets.