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

[Karl Goetz]

On Sun Aug 18 06:45:16 2013 Sam Geeraerts <address@hidden> wrote:
> 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,

> > > 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.

If things differ in the minor version would you then have a separate note on 
the doco page? That would work too.

> > 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.

Its easier for an empowered editor to do wiki redirect - server redirects are 
much harder to get at :)

> > 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

IME moinmoin doesnt branch (or merge) well though there may be a plugin of some 
sort to make it work better.

> 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.

Not sure if moinmoin search would let us make a 'search only this version' but 
i expect something could be organised.

Thanks,
kk