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

[Felipe Lopez]

2013/8/17 Karl Goetz <address@hidden>

On Sat, August 17, 2013 06:28, Felipe Lopez wrote:

[...]
 

> 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 think that's better, 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?

So, for example:

In OldStable page

#REDIRECT Documentation/2.0

In Stable page

#REDIRECT Documentation/3.0

In Dev page

#REDIRECT Documentation/4.0

Right?

 

> With this structure, the new breadcrumbs feature in the wiki could make it
> easier for the user to navigate as well.

...

> I wanted to ask first what you think, before opening a task in Savannah
> [2]
> to implement it.
>
> So, What do you think?

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

Well, I'm thinking like in book publishing, so there will be duplication.

My main concern is that I don't really know if maintaining the proposed

structure using MoinMoin requires too much manual work. For example,
I just tried to use the CopyPage [1] action in my local installation of MoinMoin
and it didn't work (action not found :(). This feature could make it easier, for
example, to copy a "stable" documentation to use it as the base for "dev"
documentation.

Sometimes I'd like to be a dictator and make the documentation team use
a DVCS [2], Sphinx [3] and RTD [4] for easier publishing :P Or use DVCS
and Mallard [5] to have all the documentation integrated in the operating
system itself (by the way, I gave Sam a documentation template [6] written in
Mallard).

[1]: http://www.gnewsense.org/HelpOnActions
[2]: http://en.wikipedia.org/wiki/Distributed_version_control_system
[3]: http://sphinx-doc.org/
[4]: https://readthedocs.org/
[5]: http://projectmallard.org/
[6]: https://bitbucket.org/sirgazil/distrohelp

--

Felipe Lopez

http://sirgazil.info/