Re: [Gnewsense-dev] Organizing wiki documentation by version

[Sam Geeraerts]

Op Sat, 17 Aug 2013 20:00:57 +0930
schreef "Karl Goetz" <address@hidden>:
> On Sat, August 17, 2013 06:28, Felipe Lopez wrote:
> > Hi,
> >
> > I've been thinking that it may be easier for users to browse the
> > documentation by version. And it would probably make it easier for
> > documentation writers to work on past, current and future
> > documentation at the same time. So, for example, some writers could
> > work on gNewSense 4 documentation without altering current
> > gNewSense 3 documentation. Currently, documentation writers are
> > updating existing gNewSense 2.x documentation pages instead of
> > creating new pages for gNewSense 3.

I like the idea. It allows for a much smoother transition of the website
to a new release.

> > We could use a URL structure like the following:
> >
> >     /Documentation/GNS_VERSION/SECTION_NAME/PAGE_TITLE
> >
> > So, for example, the installation instructions for gNewSense 3
> > would be located at:
> >
> >     /Documentation/Version3/InstallationManual/Introduction
> 
> I'd rather not say 'Version3', rather say '3.0' or similar - just a
> comment on style for thought :)

I wouldn't include a minor number, because those are only relevant for
installation media. Just '3' says what it needs to say, is nice and
short and is more language agnostic than "Version3". If that's too sec,
then we could go with 'v3', though that loses that last advantage.

> Continuing to think out loud, I'm wondering if it would be
> easier/saner to simply have oldstable/stable/dev documentation and
> pages can be renamed when appropriate. Since there might be good uses
> for permalinks oldstable/stable/dev could be redirect pages to the
> relevant release?

Those redirects could come in handy. But redirection messages in the
top of the page are slightly annoying and manually maintaining redirect
pages is inconvenient and error prone. Redirecting using the web server
could be more practical, although wiki redirects are probably necessary
anyway, unless we go for a rigid structure.

> My main concern is needing to duplicate (potentially) large tracts of
> documentation across versions where steps are almost identical.
> What happens in this case?

Is that really a problem? Any documentation before stable should be
left alone, docs for stable should be pretty stable and docs for
testing can "branch" from stable and be on their own merry way without
the need to merge back style or structure changes. The only annoyance I
can think of right now is more or less duplicate search results.