[Grok-dev] Re: updating the tutorial
Philipp von Weitershausen
philipp at weitershausen.de
Mon Mar 19 22:11:03 EDT 2007
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
>> that we shouldn't make people update the tutorial on a mandatory
>> 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
>> 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
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).
More information about the Grok-dev