Per Eriksson <pereriksson <at> openoffice.org> writes:
> Christian had a good point regarding simple instructions previously.
> 
> As you mentioned, the instructions are similar. There are big
> possibilities that we want to add platform-specific notes, comments,
> references to other documentation (e.g. the Solaris documentation) that
> is platform-specific later, letting the content remain today would give
> us most options available, which I think is a strong benefit.

I actually think that is misguided, because building instructions are changing
fast. I have brought Windows and Linux instructions pretty much up to date and
in sync. However, I also had to:

- copy a lot of useful (platform independent) information from one article to
another because it was missing there.
- delete quite some outdated/misleading information that was only
removed/updated for one platform.

If nobody actively supervises the docs and keeps them in sync, then in 6 month a
new dev will need to read the docs of _all_ platforms, if he does not want to
miss something, because lots of platform independent information was only
added/updated/removed on the article of one platform. Also the logical structure
of the articles will divert and thus make it harder for a dev to "transplant"
his knowledge from one platform to another (simply because he wouldnt be able to
easily navigate the other articles because of the different structure).

Having one article per platform would be a nifty idea - if we wrote a book and
the build enviroment wouldnt be changing. But trust me: After reading the mess
that were our build docs (scattered over way too many different places), I can
assure you: Putting platform independent infos redundant in articles for each
platform is a Bad Thing(tm).

Have Fun,

Bjoern



---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]

Reply via email to