[ZWeb] Zope.Org Docs Page Draft

Chris Withers chris at simplistix.co.uk
Mon Jul 12 05:02:17 EDT 2004


Hi Mark,

Mark wrote:
> I added two links (one of which was to ZWiki) the other ZopeMag link is  
> already on Zope.org
> anyway and tried to move things around so that we get more space.

Who's "we" here? ;-)

> but I took a first step. I'd like to encourage other people to come up  
> with their own drafts or to give
> some more suggestions / opinions about what else we should do or how to  
> structure the information.

I'm all for simplicity. That said, the much bigger problem is just keeping 
whatever documentation is referred to from that page up-to-date...

> Agreed. But I think it is a really bad idea to link so prominently to a  
> resource which hasn't
> been updated since 2001 and the most recent comment being from 2002  
> only to report
> that it has officially stalled. I'm concerned about the first  
> impressions here.

Agreed. Bear in mind how true that is of a lot of documentation to do with Zope 
though...

>> Since both the hurt^whelp system and online tutorial are in pretty  
>> poor shape, is this really what we want to do?
> 
> Well somebody thought it was important to point out before. I assume it  
> is.

That was probably just after the help system was revised, sinc then it's fallen 
in to disrepair due to lack of maintainence, which is a familar documentation 
story...

>> This needs to be done *carefully*. If you put links in a product, you  
>> restrict yourself from re-organising the site, and should really put  
>> permenant re-directing links if you *ever* move stuff. Again, not 
>> sure  we want to commit to this right now...
> 
> I certainly wouldn't want to change the URL for the docs page.

Yes, but a single link to the docs page doesn't really add much...

>>> or reflect the name and link to external resources as well.
>>
>> Agreed.
> 
> I guess that answers your why?

Well, I think Zope.org documentation implies documentation about the website 
itself, which I think totally mis-labels this section...

<SuperGuide
> Well thanks for that feedback. Part II is due next month and will of  
> course continue with what we started.
> Each part is about 15 to 20 pages. We will publish part III later this  
> year. (these will all be free)

That doesn't address the problems with Part I ;-)
I'd suggest totally rewriting Part I and bringing it up to date if you want to 
use the term SuperGuide ;-)

>> A lot of the doc projects are stalled. I'm loath to just remove them,  
>> I'd like to see a note put on the stalled ones saying "help us  
>> maintain this!" instead.
> 
> On the Contributing/Community Work page -- absolutely!

And on the resource itself. People may be stirred into action if they go looking 
for docs and find somewhere they can contribute, especially if they've just gone 
through the pain and suffering of learning a new tools and found there were no 
docs. You'll see PlacelessTranslationService grew a docs folder just recently ;-)

>>> We need a well written overview of where and how people can  contribute.
>>> (Contributing/Community Work). This should be *everyones* top  
>>> priority as it is in everybodies
>>> interest to find more volunteers to help with the tasks ahead.
>>
>> Agree with this...

How's this coming?

>> ...I totally agree with the other comments on this so far ;-)
>> This doesn't NEED two sections.
> 
> Totally disagree with the comments -- see the my answer to Jens.

Well, I can see your point, but for me "Documentation" implies the stuff in your 
"Books" section. I'd break the Articles section off into a totally seperate and 
longer page, updating as people add Articles to Zope an dpeople link to them on 
Zope.org. I'd love to see an Article and Article Link content type on Zope.org 
for this purpose...

We could vastly simplify the headings under the "Documentation" section in the 
left nav. Afterall, how is anyone who doesn't know the answer to their problem 
going to know to look in one of:
The Zope Book
Developer Guide
Administrator Guide
API Reference
(...etc...)

>>> Lots of new Zope and Plone books coming so this is important to keep  
>>> up to date.
>>
>> ...but if it's on Zope.com, how do we do that? I'd suggest a Zope  
>> Books page on Zope.org and move that into the left-column-navigation.
> 
> Don't care where the page is located -- just that it exists and be kept  
> up-to-date.

Okay, look forward to seeing it appear on Zope.org then :-)
Maybe someone from Zope.com could transplant the current page?

> Was actually hoping to see people post lots of links to this  
> mailinglist of recent (less than 3 months) articles about Zope so that  
> we can start updating the list.

I'd suggest posting again, with that as a subject on it's own. You may have more 
joy asking for sucha response on the main Zope list, this this has a pretty 
small readership...

> I'm kind of confused about your statement. There already is a link to  
> ZopeMag in the existing docs section of Zope.org --

Yes, one small link at the same level as lots of other stuff ;-)

> But if you think that ZopeMag could use some improvement -- we are  
> always looking for more writers
> and would love to see you write for us sometime.

What're your rates?

Chris

-- 
Simplistix - Content Management, Zope & Python Consulting
            - http://www.simplistix.co.uk



More information about the Zope-web mailing list