[Doc-SIG] [Python-Dev] status of development documentation
ianb at colorstudy.com
Wed Dec 21 20:43:21 CET 2005
skip at pobox.com wrote:
> Fredrik> And *everyone* knows how to write HTML.
> That's debatable. Maybe most people in the python-dev community know how.
> Even within this communitiy I suspect there are at least a few people who
> normally use something else (like Word) to generate HTML for them. I
> suspect to use the microformat stuff you'd have to restrict your authoring
> toolchain substantially, perhaps restricting it to plain old text editors.
If we were using a microformat, it is likely that the CSS class would be
used to mark content. At least that's what I've noticed in some recent
microformat specs, and there's lots of good reasons to follow that.
Tool support for adding classes to elements is relatively good; not
great from what I can tell, but good. Not that I use a lot of these
editing tools, so I might be wrong.
Still, the output of WYSIWYG tools remains very poor. Because not
everyone will be using WYSIWYG tools, it is likely that any such output
will be to be cleaned -- reindented, and probably with any unrecognized
styling removed. But this isn't that hard.
Also, I assume that most documentation maintainers will continue to use
text editors, because programmers use text editors, and this is
programer documentation. I think it is very reasonable to expect people
to know HTML; I find it unlikely that many people will enjoy authoring
HTML. I know HTML quite well, I continue to write lots of it, and I've
never enjoyed writing programming documentation in HTML. I guess in
practice I write very little HTML *content*, just structure, and when
I'm writing structure I don't mind the markup. But when I want to focus
on content the markup is very distracting, and even moreso when writing
about programming (where ASCII, newlines, and whitespace is the native
To me, using HTML feels like sacrificing the authoring experience for
expedient tools. This doesn't seem like a big step forward from LaTeX.
Ian Bicking / ianb at colorstudy.com / http://blog.ianbicking.org
More information about the Doc-SIG