[Doc-SIG] [Python-Dev] status of development documentation

[Ian Bicking]

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 
layout technique).

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