forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ferdinand Soethe <samm...@soethe.net>
Subject Re: [Proposal] Forrest Terminology
Date Wed, 11 May 2005 06:15:10 GMT

David Crossley wrote:

DC> I too find it difficult to write Forrest documentation.
DC> However, i reckon that i have managed to use carefully
DC> chosen words, and putting all commands in single quotes,
DC> and qualifying whether it is their project or the core.
DC> e.g. then do 'forrest run' to launch the local server
DC> e.g. after that, re-build the Forrest core
DC> e.g. now re-build your Forrest project

Yes, no doubt it can be done and so far everybody has managed pretty
well. 

But - to explain myself more clearly to those who are not from the
documentation side of town - it becomes a problem when you write more
and longer pieces of doc and want to use variations in language ('do a
forrest run', 'run forrest' ...) that make it easier to read and
'flow' more smoothly.

Even worse in trainings and talks where conveying quotes in spoken
language is even harder and saying command line expressions will break
your tongue and everybody else's concentration.

Not to forget writing a book where - as a writer - you are happy about
any variation you can use because after a couple of chapters you and
your readers get very tired of all these repetitions.

DC> I do agree with your drive to get better terminology.
DC> When we do, we should document it in an FAQ section,
DC> and use it consistently throughout our docs. We can then
DC> assume that people know what we mean.

Definitely. That is one one major part once we agree on the terms.
Though I'd suggest to add a glossary of terms instead of putting that
into the FAQs. (Ross, is your glossary plugIn available)?

DC> However, i am a bit concerned about the timing of these
DC> changes. We have been trying to get the 0.7 released

I'd be happy to make this (and the change in directory) structure an issue for
version 0.8 and get 0.7 rolled out now. No point in 'breaking this
over the knee' as we say in German :-)

--
Ferdinand Soethe


Mime
View raw message