Re: [Jython-dev] Proposal for new Jython User Guide - TOC

[Dave K. <dku...@re...>]

Moore, Greg <Greg_W_Moore <at> adp.com> writes:
> 
> As for stylistic and formatting changes, well I haven't thought too much
> along those lines, I've been more in the content mode. I'm not sure if
> the Jython project has a defined style. Frank, Charlie or one of the
> others may be a better resource for that. Guys, Do we have a "style
> sheet" or is it, as long as it looks good its ok? 

I'm looking at the old Jython User Guide (the one at:
http://www.jython.org/Project/userguide.html).

Looks like it was generated from reST (RestructuredText), which is also what I 
use for my course notes.  So, one approach is to use standard reST (and pay a 
little attention to the model set by the old UG), then apply the same style CSS 
sheet to our docs.  That will give us a consistent look.

Are we agreed that reST and Docutils is our preferred document format?

The existing/old user guide is, by the way, very useful.  Greg has talked about 
merging the old and new UGs.  So, I need to do some thinking about how to 
rearrange my document so as to make doing that merger easy.

> 
> I think my biggest thing is making sure there is a logical flow and that
> concepts flow from one into the next. Personally I don't like it when an
> writer introduces a new concept and then says something like 'we'll
> cover that later...' or a topic gets spread across multiple chapters.
> For example, no offence intended Dave, in 'Learning Jyhton', doc strings
> are covered in 3 or more separate places. Doc strings aren't *that*
> complicated. :)
> 

Point taken.  I've added an item to my to-do list.

> I think just a brief explanation. Maybe an example. I was thinking along
> the lines of linking into the Python docs on python.org. But would that
> make this less useful for people that want to print it out? Do we want
> to worry about that when it easily available online? What I don't want
> is a rehash/duplication of the Python docs that's pointless. It might
> get redundant but having a like that was something like: for further
> help (information?) on <TOPIC> please see docs.python.org/[topic link]

Yes.  I agree.  (1) It would be a shame not to re-use good documentation that 
is already at www.python.org/docs and (2) we want to use the power of the Web.

Dave