Understanding documentation fixes

[Tim Bosse]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

I am going to throw my point of view into the mix for what little it's
worth, considering this probably is none of my business.

With the Gutsy release, I was extremely frustrated with the lack of a
major change freeze to allow for document/code cleanup prior to string
freeze.  Several patch attempts were completely foiled by reworks that I
was unaware of that left a good portion of my time wasted as major
updates happened just before or after I had finished reviewing a
document for fixes.

If we added one or more "major change" freezes several weeks prior to
the string freeze, I would be more inclined to contribute.  This would
allow for proper testing of documentation from a technical aspect and
allow for the "cleanup crew" to get grammar and the ilk touched up.  As
Phil noted, this doesn't fix anything that occurs after string freeze.

As for changes after a release, why not give that to the mentor program
folks to maintain with one or more doc-team members to oversee the
changes?  With a good set of ground rules on how/when to submit changes,
it would allow the mentor folks to get an idea of the doc-team process
works as well as allow the doc-team time to focus on new documentation
for release+1.  If we have changes to a package after a release that
invalidates our current documentation, we should be updating the
documentation for that as well.  As Phil mentioned, this is something
that shouldn't be taken lightly considering the amount of work
within/without the doc-team.

Sorry to bug.  I just had to speak up.

Tim Bosse
taim at bosboot.org

Phil Bull wrote:
> Hi Matt,
> 
> On Sat, 2008-01-12 at 10:50 +0000, Matthew East wrote:
> [...]
>> There have often been discussions about relaxing these requirements
>> for documentation. However my personal view is that it's unlikely to
>> happen - the amount of work required to prepare a new package, test it
>> thoroughly to ensure that it won't cause breakage on the system, put
>> it through the StableReleaseUpdate process, and keep help.ubuntu.com
>> up to date as well is actually quite substantial. I'm happy to hear
>> alternative proposals though.
> 
> Here are a few proposals:
> 
>       * Release a documentation "service pack" early in the support
>         period (3 months after release should give us enough time to
>         find and fix bugs). This would consist of an updated ubuntu-docs
>         package with as many non-intrusive bug fixes as possible. There
>         would be a release schedule for this update, so that translators
>         and testers would have time to work on the package. We could
>         also use the release as an opportunity to update the online
>         docs. Advantages: All users get updated docs, online docs
>         updated. Disadvantages: Lots of work, other teams affected.
> 
>       * Release a "semi-official" update using our PPA. While most users
>         wouldn't get the update, people in need of it would be able to
>         download it. It would have to be made clear that the update
>         wasn't entirely official, though. Advantages: Updates are at
>         least available, doesn't inconvenience other teams.
>         Disadvantages: Quite a bit of work, not all users benefit.
> 
>       * Only update the website. This could again be done on a schedule,
>         so we can fix several bugs at once. However, on noticing
>         differences between the online and offline help, users might not
>         know which one to trust. Advantages: Updates available to many
>         users. Disadvantages: installed help not updated, differences
>         between online and offline help.
> 
>       * Formalise our testing/review process, so that there are fewer
>         bugs in the first place! We always end up making commits right
>         up to string freeze, even afterwards, and rarely get time to
>         properly review the docs. If we had a schedule and a structured
>         reviewing process, we could probably squash a lot of bugs before
>         release. Advantages: Better-quality documentation.
>         Disadvantages: Could still find bugs after release, DocTeam
>         members are volunteers and may not be able to fit into the
>         schedule easily.
> 
> Thanks,
> 
> Phil
> 
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)

iD8DBQFHiaeR+rF91c5MGzkRApmRAJ41XHRGew6JoBoBfT6KwHQAXriVwwCdHioM
o21u4pM62QyO534SpzZoJ64=
=enm7
-----END PGP SIGNATURE-----