Bjoern Michaelsen wrote:
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
+1
This is a very high-maintenance chunk of information. But are you ruling
out transclusion? With sub-pages, and links on the Talk pages, for easy
maintenance.
BTW, thanks for all the hard work. It looks very well done.
/tj/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@openoffice.org
For additional commands, e-mail: dev-h...@openoffice.org
