[Lazarus] Documentation style

[Hans-Peter Diettrich]

Howard Page-Clark schrieb:

>> I also can assign doc files to those people, which are willing to
>> proofread the documentation, so that we can avoid duplicate work.
> 
> I'm a native English speaker, and I'm willing to proofread 
> documentation, and make suggestions for improvements. However, I suspect 
> it is almost an endless task, and probably too much for one person to 
> undertake (although the ideal would be for one English-speaker to 
> undertake this, to get a consistent 'house style' and consistent 
> spelling [UK > US English?]).

It's a big task, but not endless. The documentation must be provided by 
the developers, or by other experienced coders. Stylistic differences 
between multiple editors should be acceptable, unless paid for ;-)

No idea about the UK/US differences. Except for Color instead of Colour ;-)

> Several questions arise immediately. Where precisely are the original 
> documents? How can I (or anyone else) be trusted to edit them correctly?

A proofreader should only make the provided text better readable, if 
required. Currently only few elements are described in a way, that 
justifies an final touch.

> What about formatting style, indenting etc. for code examples?

You can try to work out an style guide for the documentation, so that 
others can help to establish the suggested arrangement and formatting of 
the full descriptions. Good examples are a source of inspiration :-)


> It would 
> be good to have consistency here too. I notice quite a lot of 
> fpc/Lazarus source is quite terse:
> 
> [ result:=i*trunc(x/y); rather than    result := i * Trunc( x/y ); ]

I see no need for quoting code in a description. Examples instead should 
follow the formatting guidelines, more or less closely.

DoDi