Laura Creighton wrote:
>> I think the question of 'what do we need in order to share and
>> collaboratively work on documents more effectively' is the one that
>> we need to solve if we want more rapid turnover. So I would say
>> that our workflow doesn't need _shortening_ so much as _transforming
>> altogether_.
Something which hasn't come up so far is the difference in the nature of
coupling between code and documentation.
When code is broken, the right place and right way to fix it is usually (not
always) fairly obvious. When it isn't obvious, that's one of the things
python-dev is for: discussing where and how the problem should be addressed.
For documentation, the free-form nature of the prose means that there are
*many* right ways, meaning discussion is necessary much more often. The
current setup is *not* geared towards facilitating that discussion and
bringing it to a close (indeed, I believe it makes it difficult to get the
discussion going in the first place).
>> And I don't think I understand exactly all the steps
>> we have now, so it would be nice if somebody who knows this very well
>> would post them. Then we could analyse them, and see why it is that
>> we perform the way we do.
Even with the updates Trent and Neal have made to automate the documentation
update and posting process, it's still fairly disjointed.
a. Someone tries to figure out why some code of theirs isn't working by
looking at the documentation. We'll assume they eventually find the answer,
but they think a simple tweak to the "most obvious place" would have made
their search much simpler [1].
b. The online doc page they're looking at contains no obvious link
regarding where to send comments on that page. There is only a little "about
this document" link squirreled away in the footnotes.
c. We'll assume our potential contributor has found that little note, and
has gone to the about page [2].
d. General questions/comments are directed towards the email address
"[EMAIL PROTECTED]". I'm not sure *who* ends up getting those, but I'm a little
surprised it doesn't simply redirect to "doc-sig@python.org". (I could be
wrong here - it may actually do this already, or else it may go to the doc-sig
moderators for approval before being sent on to the wider list).
e. If our submitter has an SF account, they may go to SF and log a bug
report (and possibly even attach some suggested text). Again, however,
discussion is *not* facilitated - the SF bug tracker UI bites, even for
discussing code changes, let alone changes to documentation prose.
Other things that are missing in terms of facilitating dicussion:
- documentation pages don't have associated comments, making it difficult
for users to see what observations have already been made regarding particular
pages, and making it harder to review comments in light of the original text
(there's a significant disjoint between the email of SF tracker comment and
the original documentation text - source code at least has the luxury of
filenames and line numbers as an indexing system).
- domain experts can't subscribe just to areas of particular interest to
them, in order to be automatically notified when changes are made or comments
are added to those specific areas
I think Laura is right in saying that the semantic and layout markup is a side
issue - those are really there to aid the toolchain, more so than to aid the
end user.
Wiki's (particularly full-featured ones like MediaWiki or Atlassian's
Confluence, which permit comments that are separate from the main text of the
wiki page) are designed not only to allow collaborative production of content,
but also to facilitate discussion about and review of that content. And it's
that latter part we currently seem to be struggling with.
Cheers,
Nick.
[1] Step a. isn't helped by the surfeit of documentation URL's at python.org:
docs.python.org (last stable release)
www.python.org/doc ()
docs.python.org/dev (new automatically built docs)
www.python.org/dev/doc/devel (manually updated development version)
www.python.org/dev/doc/maint24 (manually updated 2.4 maintenance version)
Also, only www.python.org/doc seems to provide access to old versions.
The obvious "docs.python.org/2.4.2" doesn't work, but
"www.python.org/doc/2.4.2" does.
Lastly, the index page from the actual documentation set (which I find
quite pleasant and easy to read) is done away with for the stable versions of
the documentation, replacing it with a python.org page that uses a simple
list, rather than the clean tabular layout of the actual index page.
[2] http://docs.python.org/dev/lib/about.html
--
Nick Coghlan | [EMAIL PROTECTED] | Brisbane, Australia
---------------------------------------------------------------
http://www.boredomandlaziness.org
_______________________________________________
Doc-SIG maillist - Doc-SIG@python.org
http://mail.python.org/mailman/listinfo/doc-sig
