[Doc-SIG] Improving the documenting process.

[Nick Coghlan]

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 
"docs at python.org". I'm not sure *who* ends up getting those, but I'm a little 
surprised it doesn't simply redirect to "doc-sig at 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   |   ncoghlan at gmail.com   |   Brisbane, Australia
---------------------------------------------------------------
             http://www.boredomandlaziness.org