Jacob Kaplan-Moss
Activity tagged “documentation”
Bookmarks
Professional Book like structure with Sphinx « Lean Religion
Some good suggestions for managing and customizing the Sphinx -> LaTeX -> PDF pipeline.
Unit Testing Guidelines — pylonshq v0.0 documentation
Pylons'/Pyramid's new unit testing guidelines. *Very* good stuff here.
A Standard for Open Source Code Documentation [Alex Reisner]
A nice outline for how open source code documentation might be organized. I'm less than convinced that there needs to be a “standard,” but as a sort of conceptual framework for organizing docs this does a great job.
Pandoc
Swiss Army knife of markup formats. I'm bookmarking this specifically because it can convert HTML into reST, which I've not seen before. That means it'll be incredibly useful for converting old docs into Sphinx.
How Great is Django's Documentation?
We rock, and now I've got statistics to prove it.
How to upgrade to Django Comments 1.0 | patrickbeeson.com
Great guide to upgrading from pre-1.0 django.comments to the version in 1.0.It's quite a bit better than the one in the docs, which probably means I should ask Patrick if I can adapt this into the documentation proper.
Proven Corporation » Blog » Sphinx Templates
Some nice notes on how the Sphinx templates are laid out.
Revision 59590: /doctools/trunk
The new toolchain for the Python docs. Lots of smart stuff going on in here.
XML.com: Moving to OpenOffice: Batch Converting Legacy Documents
How to script conversion of documents through OpenOffice (and a big wad of duct tape). Works with NeoOffice, too!
PostgreSQL: Documentation: Manuals: PostgreSQL 8.2: The Statistics Collector
Info about Postgres' stats collector and associated views. I just discovered the pg_stat_user_tables and pg_stat_user_indexes views which are amazingly helpful.
pydoctor
YA python to API doc tool. But this one's by mwh, so it's likely a cut above.
Entries
Auto-building Sphinx docs
A quick tip to automatically regenerate your Sphinx docs as you make changes.
You need an editor
If you really want to produce great documentation, it needs to be edited.
Technical style
How to develop a great technical writing style.
What to write
Tech docs can take a bunch of different forms ranging from high-level overviews, to step-by-step walkthroughs, to auto-generated API documentation. Unfortunately, no single format works for all users; there’s huge differences in the way that people learn, so a well-documented project needs to provide many different forms of documentation. This is the first in a series of posts that’ll cover the art of writing good technical documentation.