We are in the process of migrating from the Trac wiki to Dokuwiki. As part
of the migration, we have decided to reorganize the documentation. Based
on conversations with James Turnbull and Luke, I have developed a plan for
the migration and restructuring, but I would like some feedback, before we
implement something that everyone is going to hate.
The plan is to have a top-level namespace for each Reductive Labs sponsored
project. Within each project namespace, we will have a Reference namespace,
a Moderated namespace, and a Community namespace. Should look something like
this:
puppet:reference
:moderated
:community
The Reference namespace will contain the inline documentation from the
actual source code. Unlike the current wiki, this reference material will
be generated only once at release time. Currently, the reference material
is dynamically generated and unnecessarily slow. We will also keep links to
reference materials for older versions of the project. The idea is to give
people online access to the relevant inline documentation, so that it can be
easily referenced.
The Moderated namespace will be an area with standardized documentation,
supported configurations, and best practices. We expect it to be in a more
structured book like format. Editorial oversight should be encouraged and
imposed by moderators. In the current wiki, there is non-relevant
information or material that could at least be presented in a more organized
manner. I know that James Turnbull has some pretty good ideas about what
this structure should be and hopefully he will be gracious enough to drive
that reorganization. We will definitely need to exert more effort in this
namespace to keep it organized and updated. We will not ,however, restrict
access to edit this wiki namespace, but instead just exert a bit more
focused editorial oversight. Restricting editing capability is not really
the wiki way. Not sure how this will work, but at the very least
individuals or groups can be notified via RSS or email when changes are made
to wiki pages.
Finally, the Community Documentation namespace will be completely open and
unmoderated. The structure will be loose and will allow community members
to create new documentation based on whatever may tickle their fancy.
The migration process should be pretty straight forward:
1. Write scripts to manage the generation of new Reference documentation
pages at release time.
2. Write scripts to convert from trac to Dokuwiki and place all existing
wiki content in the Community documentation namespace.
3. Freeze changes to current wiki, and migrate to Dokuwiki.
4. Hopefully some kind soul will volunteer to take lead on creating an
awesome new structure within the Moderated namespace.
5. Within the new structure, the community will help migrate relevant
materials from the Community documentation to the Moderated documentation.
I'd like to hear what you think of this plan. Does the structure sound
reasonable? I have most of the work done for a straight migration from trac
to dokuwiki. Really all that is left is to fix the broken links and tagging
and develop a process for generating the Reference documentation when new
versions of a given project are released.
Cheers,
Teyo
--
Teyo Tyree :: www.reductivelabs.com :: +1.615.275.5066
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"Puppet Developers" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to
[email protected]
For more options, visit this group at
http://groups.google.com/group/puppet-dev?hl=en
-~----------~----~----~----~------~----~------~--~---
