[Grok-dev] Re: updating the tutorial

[Philipp von Weitershausen]

On 19 Mar 2007, at 19:19 , Martijn Faassen wrote:
>> > It's essential to the success of this project however. I've  
>> tried to
>> > make setting up the examples as fast as possible too: read
>> > doc/groktut/INSTALL.txt
>>
>> Thank you for taking the time to write this down. I'm inclined to  
>> argue
>> that we shouldn't make people update the tutorial on a mandatory  
>> basis.
>> People will be sloppy (just look at me :)) and people will not always
>> get it right.
>
> People should at the very least mark changes that have an effect on
> the tutorial. What would be the right place for this? We should
> starting maintaining a CHANGES.txt file anyhow, perhaps that can be
> used for this.

That sounds like a better idea. Perhaps not CHANGES.txt but a doc/ 
TODO.txt file so that we can keep track of which changes have been  
incorporated in the docs (by removing them from doc/TODO.txt)?

>> Also, I plan to do some work on the reference soon. If we
>> made people update that at the same time, we'll increase the  
>> burden even
>> further (not to mention we already make people write doctests,  
>> which is
>> a good thing but it's a burden).
>>
>> I realize the importance of the documentation, but I'd hate to see  
>> the
>> bar for Grok development raised too much.
>
> It's a difficult balance to make. Just realize that running an
> individual buildout of a tutorial is extremely fast (after the first
> time).

I do realize that. It's still another couple of steps I have to do  
after checkins, ignoring the fact that I'd have to edit the tutorial  
text as well.

I'm not arguing against maintaining the tutorial. It's just that I  
currently find that I'm not really familiar with where the tutorial  
is going and I figure other people aren't either. Perhaps it needs to  
flesh out a bit first and gain a bit more structure. It isn't that  
hard to find your way through it right now, but it's not always  
obvious (the table of contents that I added for the rendered HTML  
helps a bit).