Mailing List Archive

Jose Luis Rivero wrote:
> Hi *:

> 1. Currently, there are no official maintained handbooks. We have the
> networking handbooks (/doc/*/handbook/handbook-*) marked as draft and
> the networkless docs which refers to latest stable release (2007.0)
> marked as unmaintained.

/doc/en/handbook/ and /doc/en/handbook/2008.0/ are officially maintained.
Them being marked 'draft' does not make them any less official.
/doc/en/handbook/2007.0/ is officially unmaintained.

> 2. There are no docs covering a networking installation for the latest
> stable release. Users who don't want to use the beta can't find the
> docs to make a network based installation since they were overwriting
> by 2008.0 (which is still a beta).

draft was moved up because anyone using the latest docs and a 2007.0 media on
a modern system (read about 1 year old or more recent) could not go very far
in the installation process. Besides, those completing a 2007.0 install would
then need to upgrade some many packages that it was deemed better to move up
the draft version.

> One idea for next time could be keeping current and networkless
> handbooks maintained until the release reaches an stable status and

Networkless will always be under xxxx.y
2007.0 is still there, 2008.0 is already there.
If anything needs to change, the arches that have a GUI installer would only
get "pop CD into your reader, boot, follow on-screen instructions". Done!

> develop the new docs in /doc/*/handbook/beta/

That is done in /doc/en/handbook/draft/
We moved it up earlier than at official release time as already explained.


Cheers,
--
/ Xavier Neys
\_ Gentoo Documentation Project
/
/\ http://www.gentoo.org/doc/en/

On Sat, Apr 26, 2008 at 09:42:38PM +0200, Xavier Neys wrote:
> Jose Luis Rivero wrote:
>> 1. Currently, there are no official maintained handbooks. We have the
>> networking handbooks (/doc/*/handbook/handbook-*) marked as draft and
>> the networkless docs which refers to latest stable release (2007.0)
>> marked as unmaintained.
>
> /doc/en/handbook/ and /doc/en/handbook/2008.0/ are officially maintained.
> Them being marked 'draft' does not make them any less official.

"Disclaimer : This document is a work in progress and should not be
considered official yet."

Probably people reading this is not going to consider them as official.

>
>> 2. There are no docs covering a networking installation for the latest
>> stable release. Users who don't want to use the beta can't find the
>> docs to make a network based installation since they were overwriting
>> by 2008.0 (which is still a beta).
>
> draft was moved up because anyone using the latest docs and a 2007.0 media
> on a modern system (read about 1 year old or more recent) could not go very
> far in the installation process. Besides, those completing a 2007.0 install
> would then need to upgrade some many packages that it was deemed better to
> move up the draft version.

Maybe some kind of warning or note about this can help the people to
understand the situation.

>
>> One idea for next time could be keeping current and networkless
>> handbooks maintained until the release reaches an stable status and
>
> Networkless will always be under xxxx.y
> 2007.0 is still there, 2008.0 is already there.

"Disclaimer : This handbook has been replaced by a newer version and
is not maintained anymore." This warning in 2007.0 is not going to make the
users go for this and if you try to find a newer version all you have is
a beta. Same problem than above.

I'm for keeping networkless under xxxx.y but keep the latest stable
version out of 'unmantained' could help during beta phase.

>> develop the new docs in /doc/*/handbook/beta/
>
> That is done in /doc/en/handbook/draft/
> We moved it up earlier than at official release time as already explained.

ACK.

Thanks Xavier.

--
Jose Luis Rivero <yoswink@gentoo.org>
Gentoo/Doc Gentoo/Alpha

--
gentoo-doc@lists.gentoo.org mailing list

Jose Luis Rivero wrote:
> On Sat, Apr 26, 2008 at 09:42:38PM +0200, Xavier Neys wrote:
>> Jose Luis Rivero wrote:
>>> 1. Currently, there are no official maintained handbooks. We have the
>>> networking handbooks (/doc/*/handbook/handbook-*) marked as draft and
>>> the networkless docs which refers to latest stable release (2007.0)
>>> marked as unmaintained.
>> /doc/en/handbook/ and /doc/en/handbook/2008.0/ are officially maintained.
>> Them being marked 'draft' does not make them any less official.
>
> "Disclaimer : This document is a work in progress and should not be
> considered official yet."
>
> Probably people reading this is not going to consider them as official.
>
>>> 2. There are no docs covering a networking installation for the latest
>>> stable release. Users who don't want to use the beta can't find the
>>> docs to make a network based installation since they were overwriting
>>> by 2008.0 (which is still a beta).
>> draft was moved up because anyone using the latest docs and a 2007.0 media
>> on a modern system (read about 1 year old or more recent) could not go very
>> far in the installation process. Besides, those completing a 2007.0 install
>> would then need to upgrade some many packages that it was deemed better to
>> move up the draft version.
>
> Maybe some kind of warning or note about this can help the people to
> understand the situation.
>
>>> One idea for next time could be keeping current and networkless
>>> handbooks maintained until the release reaches an stable status and
>> Networkless will always be under xxxx.y
>> 2007.0 is still there, 2008.0 is already there.
>
> "Disclaimer : This handbook has been replaced by a newer version and
> is not maintained anymore." This warning in 2007.0 is not going to make the
> users go for this and if you try to find a newer version all you have is
> a beta. Same problem than above.
>
> I'm for keeping networkless under xxxx.y but keep the latest stable
> version out of 'unmantained' could help during beta phase.
>
>>> develop the new docs in /doc/*/handbook/beta/
>> That is done in /doc/en/handbook/draft/
>> We moved it up earlier than at official release time as already explained.
>
> ACK.
>
> Thanks Xavier.

As you know, the packages are still stable whether in 2007.0 or
2008.0betaX. There's no practical difference between the two, though
obviously you won't have so many updates if you use a beta tarball. The
only difference is the LiveCDs/DVDs.

Assuming this trend of public betas continues through coming releases,
we may want to add a note explaining this -- that the installed system
and packages are identical to the latest versions in Portage; it's only
the media that's "beta". Or we could even add one now, and make it
conditional on something like an "is_beta" key or similar in the TOC.

On Sat, Apr 26, 2008 at 10:04:04PM -0700, Josh Saddler wrote:
> As you know, the packages are still stable whether in 2007.0 or
> 2008.0betaX. There's no practical difference between the two, though
> obviously you won't have so many updates if you use a beta tarball. The
> only difference is the LiveCDs/DVDs.

Well, with the new release you are using different (and uptodate) stages
than current ones and different profiles, which could generate some
problems under specific circunstances, this is one of the reason what
the beta is for, imho.

But you are right, the packages are the same.

> Assuming this trend of public betas continues through coming releases, we
> may want to add a note explaining this -- that the installed system and
> packages are identical to the latest versions in Portage; it's only the
> media that's "beta". Or we could even add one now, and make it conditional
> on something like an "is_beta" key or similar in the TOC.
>

I'm for working in xxxx.y and draft/ until the stable release is done
(if there is no special cases like currently). Your idea can help people
to understand what a beta release for Gentoo means but please apply it
along with not overwritting current handbooks until the release is
stable.

Maybe you can make a new 'disclaimer' value, beta_release (or whatever)
and put it instead of draft, which usually refers to docs non finalized
or waiting for review, which is not the case.

Thanks Josh.

--
Jose Luis Rivero <yoswink@gentoo.org>
Gentoo/Doc Gentoo/Alpha

--
gentoo-doc@lists.gentoo.org mailing list

Jose Luis Rivero wrote:
> I'm for working in xxxx.y and draft/ until the stable release is done
> (if there is no special cases like currently). Your idea can help people
> to understand what a beta release for Gentoo means but please apply it
> along with not overwritting current handbooks until the release is
> stable.
>
> Maybe you can make a new 'disclaimer' value, beta_release (or whatever)
> and put it instead of draft, which usually refers to docs non finalized
> or waiting for review, which is not the case.

I, personally, hate the whole business of copying stuff to draft/ and
then back again. It's a pain, and there's some risk of forgetting stuff
or not getting it moved or forgetting to delete old files (this happened
once or twice with this release). That's why I dispensed with doing
draft/2008.0/ and just went straight to the toplevel dir.

However, draft is nice to have a workspace for committing networked HB
changes to make sure they don't get lost. That's the only reason I can
think of for not punting it entirely.

I suppose if we were on git, it'd be easier to make our commits but not
push them onto the final versions. Maybe. Who knows. :)

As I see it, we have a few options:

1. Keep the "draft" disclaimer for the beta handbooks, the only live
versions available.
2. Add listings for "beta" in addition to "latest stable" (really old)
in our index, and link to them.
3. Add disclaimer to TOC for beta status. Replaces(?) draft disclaimer.
4. Ditch the draft disclaimer, and instead just consider each handbook a
"release" handbook. We just use the beta stage/file/mirror names. Since
the only thing that's in testing is the CDs, really.

I'm all for 1, 3, or 4. My personal favorite is 4. Thoughts?

On 4/27/08, Josh Saddler <nightmorph@gentoo.org> wrote:
> I, personally, hate the whole business of copying stuff to draft/ and then
> back again. It's a pain, and there's some risk of forgetting stuff or not
> getting it moved or forgetting to delete old files (this happened once or
> twice with this release). That's why I dispensed with doing draft/2008.0/
> and just went straight to the toplevel dir.
[...]
> As I see it, we have a few options:
>
> 1. Keep the "draft" disclaimer for the beta handbooks, the only live
> versions available.
> 2. Add listings for "beta" in addition to "latest stable" (really old) in
> our index, and link to them.
> 3. Add disclaimer to TOC for beta status. Replaces(?) draft disclaimer.
> 4. Ditch the draft disclaimer, and instead just consider each handbook a
> "release" handbook. We just use the beta stage/file/mirror names. Since the
> only thing that's in testing is the CDs, really.
>
> I'm all for 1, 3, or 4. My personal favorite is 4. Thoughts?

Mine is 4 as well. The "2008_beta" handbook for GDP is a "production"
handbook - the release is publically available and all the disclaimers
for the _beta release should automatically apply to its documentation
as well.

If you use 2008_beta, you definitely expect that the handbooks can
contain some minor bugs as well. If you don't want to use the _beta,
you're still free to use the 2007 release media (including docs).
Releng doesn't "support" 2007.0 (i.e. there will not be a 2007 fix) so
afaik, 2007.0 for releng is also unmaintained. Why keep the
documentation officially maintained then?

After all, the (Internet-less) documentation is tied to the release...

Wkr,
Sven Vermeulen
--
gentoo-doc@lists.gentoo.org mailing list

2008/4/28 Sven Vermeulen <swift@gentoo.org>:
> On 4/27/08, Josh Saddler <nightmorph@gentoo.org> wrote:
> > I, personally, hate the whole business of copying stuff to draft/ and then
> > back again. It's a pain, and there's some risk of forgetting stuff or not
> > getting it moved or forgetting to delete old files (this happened once or
> > twice with this release). That's why I dispensed with doing draft/2008.0/
> > and just went straight to the toplevel dir.
> [...]
>
> > As I see it, we have a few options:
> >
> > 1. Keep the "draft" disclaimer for the beta handbooks, the only live
> > versions available.
> > 2. Add listings for "beta" in addition to "latest stable" (really old) in
> > our index, and link to them.
> > 3. Add disclaimer to TOC for beta status. Replaces(?) draft disclaimer.
> > 4. Ditch the draft disclaimer, and instead just consider each handbook a
> > "release" handbook. We just use the beta stage/file/mirror names. Since the
> > only thing that's in testing is the CDs, really.
> >
> > I'm all for 1, 3, or 4. My personal favorite is 4. Thoughts?
>
> Mine is 4 as well. The "2008_beta" handbook for GDP is a "production"
> handbook - the release is publically available and all the disclaimers
> for the _beta release should automatically apply to its documentation
> as well.

Yeah. #4 is the best option.
--
gentoo-doc@lists.gentoo.org mailing list