Hi all Luke and I have been discussing the wiki and how its future development might pan out. As a result I thought I''d canvas people for feedback. Currently the wiki''s layout and structure is fairly ad hoc and it''s a mix of wiki mark-up and REStructured Text (RST). We''d like to make it more "manual" like or at least move a significant portion of the non-introductary material into a "manual" like format. Some options and ideas: 1. Move the wiki from Trac to something else. Some options have been proposed: a. Drupal - the book format (does not support RST though AFAIK) b. MoinMoin (supports RST) c. Redmine''s internal wiki (requires parsing the RST - currently not possible in Redmine) - as part of a migration to Redmine over Trac. 2. Restructure the wiki in place on Trac 3. Leave the wiki alone - it''s perfect! Other ideas, thoughts, comments? Regards James Turnbull -- James Turnbull (james@lovedthanlost.net) Author of: * Pulling Strings with Puppet (http://www.amazon.com/gp/product/1590599780/) * Pro Nagios 2.0 (http://www.amazon.com/gp/product/1590596099/) * Hardening Linux (http://www.amazon.com/gp/product/1590594444/) --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Puppet Developers" group. To post to this group, send email to puppet-dev@googlegroups.com To unsubscribe from this group, send email to puppet-dev-unsubscribe@googlegroups.com For more options, visit this group at http://groups.google.com/group/puppet-dev?hl=en -~----------~----~----~----~------~----~------~--~---
On Fri, May 09, 2008 at 01:07:55AM +1000, James Turnbull wrote:> 2. Restructure the wiki in place on TracWhy not? I don''t see the reason for switching the wiki engine. -- Why bother building more nukes until we use the ones we already have?
Steven Jenkins
2008-May-08 16:08 UTC
[Puppet Users] Re: [Puppet-dev] The wiki - directions and ideas
On Thu, May 8, 2008 at 11:07 AM, James Turnbull <james@lovedthanlost.net> wrote:> > Hi all > > Luke and I have been discussing the wiki and how its future development > might pan out. As a result I thought I''d canvas people for feedback. > > Currently the wiki''s layout and structure is fairly ad hoc and it''s a > mix of wiki mark-up and REStructured Text (RST). We''d like to make it > more "manual" like or at least move a significant portion of the > non-introductary material into a "manual" like format. >I agree that the existing wiki is pretty hard to follow and find useful information. It might actually be helpful to coordinate a ''docathon'' first and do a clean up of the existing data before making a decision about any further wiki changes (e.g., migrating to a different platform).> Some options and ideas: > > 1. Move the wiki from Trac to something else. Some options have been > proposed: > > a. Drupal - the book format (does not support RST though AFAIK) > b. MoinMoin (supports RST) > c. Redmine''s internal wiki (requires parsing the RST - currently not > possible in Redmine) - as part of a migration to Redmine over Trac. >While many of the various CMS''s are configurable, and can be made to do just about everything, I personally like the out-of-the-box look and feel of MediaWiki. It''s defaults ''make sense''.> 2. Restructure the wiki in place on Trac >I''d not suggest that.> 3. Leave the wiki alone - it''s perfect! >Nor would I suggest that. Steven --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com To unsubscribe from this group, send email to puppet-users-unsubscribe@googlegroups.com For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en -~----------~----~----~----~------~----~------~--~---
Digant C Kasundra
2008-May-08 16:48 UTC
Re: [Puppet Users] The wiki - directions and ideas
--On Friday, May 09, 2008 1:07 AM +1000 James Turnbull <james@lovedthanlost.net> wrote:> > Hi all > > Luke and I have been discussing the wiki and how its future development > might pan out. As a result I thought I''d canvas people for feedback. > > Currently the wiki''s layout and structure is fairly ad hoc and it''s a > mix of wiki mark-up and REStructured Text (RST). We''d like to make it > more "manual" like or at least move a significant portion of the > non-introductary material into a "manual" like format. > > Some options and ideas: > > 1. Move the wiki from Trac to something else. Some options have been > proposed: > > a. Drupal - the book format (does not support RST though AFAIK) > b. MoinMoin (supports RST) > c. Redmine''s internal wiki (requires parsing the RST - currently not > possible in Redmine) - as part of a migration to Redmine over Trac. > > 2. Restructure the wiki in place on Trac > > 3. Leave the wiki alone - it''s perfect! > > Other ideas, thoughts, comments? > > Regards > > James TurnbullAs a document wrangler, I didn''t get to do much wrangling and I first want to apologize to the community for that. Apparently, Stanford has other ideas of what I should be doing with my time. :) :( Anyway, I think a restructuring and moving to something like MoinMoin or Ikiwiki or the such would be great. And the flow could use some definitely improvement. I still rely on the search function to find pages I''m looking for all too often. --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Puppet Developers" group. To post to this group, send email to puppet-dev@googlegroups.com To unsubscribe from this group, send email to puppet-dev-unsubscribe@googlegroups.com For more options, visit this group at http://groups.google.com/group/puppet-dev?hl=en -~----------~----~----~----~------~----~------~--~---
--On Thursday, May 08, 2008 11:21 AM -0400 The Anarcat <anarcat@anarcat.ath.cx> wrote:>> 2. Restructure the wiki in place on Trac > > Why not? I don''t see the reason for switching the wiki engine.Because trac makes me cry at night. I don''t know what it is about it, either. One thing is that for some reason, I have to login twice before I can do anything. --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Puppet Developers" group. To post to this group, send email to puppet-dev@googlegroups.com To unsubscribe from this group, send email to puppet-dev-unsubscribe@googlegroups.com For more options, visit this group at http://groups.google.com/group/puppet-dev?hl=en -~----------~----~----~----~------~----~------~--~---
--On Thursday, May 08, 2008 12:08 PM -0400 Steven Jenkins <steven.jenkins@gmail.com> wrote:> I agree that the existing wiki is pretty hard to follow and find > useful information. It might actually be helpful to coordinate a > ''docathon'' first and do a clean up of the existing data before making > a decision about any further wiki changes (e.g., migrating to a > different platform).Luke, did the doc maintainers list get migrated over? If so, anyone interested in helping with this effort should jump on that list and we can do the docathon there. --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Puppet Developers" group. To post to this group, send email to puppet-dev@googlegroups.com To unsubscribe from this group, send email to puppet-dev-unsubscribe@googlegroups.com For more options, visit this group at http://groups.google.com/group/puppet-dev?hl=en -~----------~----~----~----~------~----~------~--~---
I''m a TWiki fan, and have used it in many companies and projects. My $0.02. ;] I could donate some time to reformat existing docs. On Thu, May 08, 2008 at 09:48:32AM -0700, Digant C Kasundra wrote:> > --On Friday, May 09, 2008 1:07 AM +1000 James Turnbull > <james@lovedthanlost.net> wrote: > > > > > Hi all > > > > Luke and I have been discussing the wiki and how its future development > > might pan out. As a result I thought I''d canvas people for feedback. > > > > Currently the wiki''s layout and structure is fairly ad hoc and it''s a > > mix of wiki mark-up and REStructured Text (RST). We''d like to make it > > more "manual" like or at least move a significant portion of the > > non-introductary material into a "manual" like format. > > > > Some options and ideas: > > > > 1. Move the wiki from Trac to something else. Some options have been > > proposed: > > > > a. Drupal - the book format (does not support RST though AFAIK) > > b. MoinMoin (supports RST) > > c. Redmine''s internal wiki (requires parsing the RST - currently not > > possible in Redmine) - as part of a migration to Redmine over Trac. > > > > 2. Restructure the wiki in place on Trac > > > > 3. Leave the wiki alone - it''s perfect! > > > > Other ideas, thoughts, comments? > > > > Regards > > > > James Turnbull > > As a document wrangler, I didn''t get to do much wrangling and I first want > to apologize to the community for that. Apparently, Stanford has other > ideas of what I should be doing with my time. :) :( > > Anyway, I think a restructuring and moving to something like MoinMoin or > Ikiwiki or the such would be great. And the flow could use some definitely > improvement. I still rely on the search function to find pages I''m looking > for all too often. > > > > >------------------------------------------------------------------ Russell Adams RLAdams@AdamsInfoServ.com PGP Key ID: 0x1160DCB3 http://www.adamsinfoserv.com/ Fingerprint: 1723 D8CA 4280 1EC9 557F 66E8 1154 E018 1160 DCB3 --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com To unsubscribe from this group, send email to puppet-users-unsubscribe@googlegroups.com For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en -~----------~----~----~----~------~----~------~--~---
Russ Allbery
2008-May-08 20:15 UTC
[Puppet Users] Re: [Puppet-dev] The wiki - directions and ideas
James Turnbull <james@lovedthanlost.net> writes:> Some options and ideas: > > 1. Move the wiki from Trac to something else. Some options have been > proposed: > > a. Drupal - the book format (does not support RST though AFAIK) > b. MoinMoin (supports RST) > c. Redmine''s internal wiki (requires parsing the RST - currently not > possible in Redmine) - as part of a migration to Redmine over Trac.I suggest also taking a look at ikiwiki <http://ikiwiki.info/>. It may not be quite what you''re looking for, but the major points in its favor are: * Designed from the start to use an SCM as its file backend, with full support for that SCM being Git. ikiwiki will use its own Git clone of the repository and knows how to push changes to a master repository and pull changes back from it, which means that it can even use Git merging to handle simultaneous changes to the same page. * Designed to permit everything that you can do over the web interface via straight manipulation of the underlying repository, so you can write pages in your favorite text editor and just commit them to Git and have the right things happen. * Uses whichever standard wiki markup language you want. It comes with support for MarkDown and has standard plugins for WikiText, reStructuredText, and Textile. * Very modular with a lot of community-developed plugins. One possible drawback for folks here is that it''s written in Perl, but it''s written by a Perl developer for whom I have a lot of respect (Joey does a lot of stuff in Debian and maintains the Debian build helpers used by the vast majority of Debian packages). -- Russ Allbery (rra@stanford.edu) <http://www.eyrie.org/~eagle/> --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com To unsubscribe from this group, send email to puppet-users-unsubscribe@googlegroups.com For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en -~----------~----~----~----~------~----~------~--~---
Blake Barnett
2008-May-08 21:01 UTC
[Puppet Users] Re: [Puppet-dev] The wiki - directions and ideas
On May 8, 2008, at 8:07 AM, James Turnbull wrote: <snip>> Some options and ideas: > > 1. Move the wiki from Trac to something else. Some options have been > proposed: > > a. Drupal - the book format (does not support RST though AFAIK) > b. MoinMoin (supports RST) > c. Redmine''s internal wiki (requires parsing the RST - currently not > possible in Redmine) - as part of a migration to Redmine over Trac. > > 2. Restructure the wiki in place on Trac > > 3. Leave the wiki alone - it''s perfect!First of all, let me just say that I think the people who contribute the most documentation automatically get to make this decision. It should be whatever they prefer. That said... +1 Redmine, for project workflow, forums, and ruby goodness. I prefer Markdown to rST but obviously it''s not as flexible for transformation. It does have the added bonuses of being available now, and familiar to anyone who''s written plaintext documentation. I think Ikiwiki is a great choice (though it will require the most work aesthetically!). -Blake --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com To unsubscribe from this group, send email to puppet-users-unsubscribe@googlegroups.com For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en -~----------~----~----~----~------~----~------~--~---
Hello, I do like drupal very much, and I have done a lot of developing for it. I am using it for some years now. Since I also like puppet very much, I would spent some time to help in migrating the documentation to drupal. Also, I would like to help - developing a theme (i.e: converting reductivelabs theme to a drupal theme) - setting drupal up - giving advice in module selection and such Why would I prefer drupal instead of a wiki? - my experience with wikis shows that they tend to become very chaotic over time. - drupal''s books is a very nice way to create structured manuals. I think one could take any other proper CMS, it must not be drupal. Nevertheless, wikis are no proper CMSes. There is a huge difference, IMHO. Anymay, if it is the functionality of a wiki that one wants (easily link content) then drupal can do that also. btw.: is RST this? http://docutils.sourceforge.net/rst.html If so, I think it is very similar to the textile markup language, and could be easily converted to that. Regards, udo. On 08.05.2008, at 17:07, James Turnbull wrote:> > Hi all > > Luke and I have been discussing the wiki and how its future > development > might pan out. As a result I thought I''d canvas people for feedback. > > Currently the wiki''s layout and structure is fairly ad hoc and it''s a > mix of wiki mark-up and REStructured Text (RST). We''d like to make it > more "manual" like or at least move a significant portion of the > non-introductary material into a "manual" like format. > > Some options and ideas: > > 1. Move the wiki from Trac to something else. Some options have been > proposed: > > a. Drupal - the book format (does not support RST though AFAIK) > b. MoinMoin (supports RST) > c. Redmine''s internal wiki (requires parsing the RST - currently not > possible in Redmine) - as part of a migration to Redmine over Trac. > > 2. Restructure the wiki in place on Trac > > 3. Leave the wiki alone - it''s perfect! > > Other ideas, thoughts, comments? > > Regards > > James Turnbull > > -- > James Turnbull (james@lovedthanlost.net) > > Author of: > * Pulling Strings with Puppet > (http://www.amazon.com/gp/product/1590599780/) > * Pro Nagios 2.0 > (http://www.amazon.com/gp/product/1590596099/) > * Hardening Linux > (http://www.amazon.com/gp/product/1590594444/) > > > --~--~---------~--~----~------------~-------~--~----~ > You received this message because you are subscribed to the Google > Groups "Puppet Users" group. > To post to this group, send email to puppet-users@googlegroups.com > To unsubscribe from this group, send email to puppet-users-unsubscribe@googlegroups.com > For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en > -~----------~----~----~----~------~----~------~--~--- >-- :: udo waechter - root@zoide.net :: N 52º16''30.5" E 8º3''10.1" :: genuine input for your ears: http://auriculabovinari.de :: your eyes: http://ezag.zoide.net :: your brain: http://zoide.net
On May 8, 11:07 am, James Turnbull <ja...@lovedthanlost.net> wrote:> Currently the wiki''s layout and structure is fairly ad hoc and it''s a > mix of wiki mark-up and REStructured Text (RST). We''d like to make it > more "manual" like or at least move a significant portion of the > non-introductary material into a "manual" like format.I agree that the current documentation is quite erratic. Most of the problems I have with it stem from the fact that the search is not clean and that pages often conflict with one another. I think Trac is specifically responsible for the search quality. Every time I search I get a whole lot of "garbage" links back (source code, comments, etc.) and even the good links have mangled text at the beginning. Trac works much better as a SCM than a documentation tool. As far as conflicting pages go, what I mean is that there are several places where you find documentation on how to do something (adding custom Facts) but then it tells you that if your using 0.2.3+ you have to do it completely different. I''m not sure if this is a failing of Trac or just the way its set up for Puppet. One thing a "real" wiki would provide is depreciation pages and redirects. Something like Wikipedia or TWiki comes to mind. I also do not like the RST functionality - it''s not needed and it really confuses contributors (or at least it confuses me :).> Some options and ideas: > > 1. Move the wiki from Trac to something else. Some options have been > proposed: > > a. Drupal - the book format (does not support RST though AFAIK) > b. MoinMoin (supports RST) > c. Redmine''s internal wiki (requires parsing the RST - currently not > possible in Redmine) - as part of a migration to Redmine over Trac.a. I''m not sure Drupal would be appropriate. Does it allow public commentary/editing like a Wiki or does it have more or an edit->authorize->publish work flow?b. MoinMoin would be fine, although again I don''t see the need for RST. c. I don''t really have an opinion on Redmine but I do think that embedded wikis loose some of their power and would rather us have a separate one. Disclaimer: My company sells an issue tracking solution so I am not going to comment on converting to Redmine or Trac. :)> 2. Restructure the wiki in place on TracThis could work, but I''m not sure how much work it would be. Two things would be necessary: eliminate RST unless someone could explain why its necessary, and completely revamp the search engine. Maybe a Google search box would work.> 3. Leave the wiki alone - it''s perfect!No. Currently, I find it very difficult to find the quality docs that do exist in the wiki.> Other ideas, thoughts, comments?I really don''t have a preference with regards to a specific wiki. I have used Wikipedia and I like it quite well. I have implemented TWiki and it was pretty easy to setup and configure, I also like the fact that it saves to a plain file system and not a database for easy backup & restore, but that''s just me. The bottom line is that I don''t really care which stand-alone Wiki we use as I think they are all fairly equal, but maybe a Ruby one would be most appropriate. :) Later... Richard --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com To unsubscribe from this group, send email to puppet-users-unsubscribe@googlegroups.com For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en -~----------~----~----~----~------~----~------~--~---
On May 8, 12:52 pm, Digant C Kasundra <dig...@stanford.edu> wrote:> --On Thursday, May 08, 2008 11:21 AM -0400 The Anarcat > > <anar...@anarcat.ath.cx> wrote: > >> 2. Restructure the wiki in place on Trac > > > Why not? I don''t see the reason for switching the wiki engine. > > Because trac makes me cry at night. I don''t know what it is about it, > either. One thing is that for some reason, I have to login twice before I > can do anything.For me it is the quality of the search results. Very rarely do I want to search Changesets or Source Code but it forces me to anyway. Worse still how it mungs up the results with a bunch of "header" garbage (PuppetScalability: {{{ #!rst ======================== Puppet Scalability ...) in all the links. Later... Richard --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com To unsubscribe from this group, send email to puppet-users-unsubscribe@googlegroups.com For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en -~----------~----~----~----~------~----~------~--~---
On May 12, 2008, at 10:23 AM, Richard wrote:> For me it is the quality of the search results. Very rarely do I want > to search Changesets or Source Code but it forces me to anyway. Worse > still how it mungs up the results with a bunch of "header" garbage > (PuppetScalability: {{{ #!rst ======================== Puppet > Scalability ...) in all the links.Yeah, this is because Trac is smart enough to render rst when displaying the whole page, but not when displaying snippets. -- There are three social classes in America: upper middle class, middle class, and lower middle class. --Judith Martin --------------------------------------------------------------------- Luke Kanies | http://reductivelabs.com | http://madstop.com --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com To unsubscribe from this group, send email to puppet-users-unsubscribe@googlegroups.com For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en -~----------~----~----~----~------~----~------~--~---
On May 12, 2008, at 10:19 AM, Richard wrote:> I also do not like the RST > functionality - it''s not needed and it really confuses contributors > (or at least it confuses me :).I agreed with most of your commentary, but I''m going to tow a hard line on using some kind of standard format, and I''d really prefer that that format be easy to convert to non-html formats also, like PDF and ''man'' pages. RST is, by far, the most completely and useful markup. It pays a slight cost in usability, for its difficulty scales pretty well -- headlines, bold, and italics are wicked easy, tables and footnotes take a bit more work. -- I''m worried about Bart. Today, he''s sucking people''s blood, tommorrow he might be smoking. -Marge Simpson --------------------------------------------------------------------- Luke Kanies | http://reductivelabs.com | http://madstop.com --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com To unsubscribe from this group, send email to puppet-users-unsubscribe@googlegroups.com For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en -~----------~----~----~----~------~----~------~--~---
On May 12, 2008, at 8:24 AM, udo waechter wrote:> btw.: is RST this? http://docutils.sourceforge.net/rst.html > If so, I think it is very similar to the textile markup language, > and could be easily converted to that.Yes, it is. It bears some resemblance to textile, but textile is essentially an html-only markup; it''s never going to be useful for generating PDFs, for instance. I kinda hate textile as a result. -- It is well to remember that the entire universe, with one trifling exception, is composed of others. --John Andrew Holmes --------------------------------------------------------------------- Luke Kanies | http://reductivelabs.com | http://madstop.com --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com To unsubscribe from this group, send email to puppet-users-unsubscribe@googlegroups.com For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en -~----------~----~----~----~------~----~------~--~---
On Mon, May 12, 2008 at 9:12 AM, Luke Kanies <luke@madstop.com> wrote:> On May 12, 2008, at 10:19 AM, Richard wrote: > > > I also do not like the RST > > functionality - it''s not needed and it really confuses contributors > > (or at least it confuses me :). > > RST is, by far, the most completely and useful markup. It pays a > slight cost in usability, for its difficulty scales pretty well -- > headlines, bold, and italics are wicked easy, tables and footnotes > take a bit more work.+1. RST is not the question here. It is an excellent format in it''s flexibility and existing tools for converting/manipulating it. Our embedded docs are already in RST and I for one don''t see the payoff in converting them. Let''s keep this discussion about the wiki/Trac. Does our solution really need to have RST as a "native" format? Why can''t we use existing RST tools to serve up the RST docs as HTML? Maybe I''m missing something? --Paul --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com To unsubscribe from this group, send email to puppet-users-unsubscribe@googlegroups.com For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en -~----------~----~----~----~------~----~------~--~---
On May 12, 2008, at 12:03 PM, Paul Lathrop wrote:> Does our solution really need to have RST as a "native" format? Why > can''t we use existing RST tools to serve up the RST docs as HTML? > Maybe I''m missing something?I think that''s where we should focus our efforts for now. That should be an easy hack to start with, and we can always write a native converter later. -- In our civilization, and under our republican form of government, intelligence is so highly honored that it is rewarded by exemption from the cares of office. --Ambrose Bierce --------------------------------------------------------------------- Luke Kanies | http://reductivelabs.com | http://madstop.com --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com To unsubscribe from this group, send email to puppet-users-unsubscribe@googlegroups.com For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en -~----------~----~----~----~------~----~------~--~---
Hi, On 12.05.2008, at 17:19, Richard wrote:> > On May 8, 11:07 am, James Turnbull <ja...@lovedthanlost.net> wrote: > a. I''m not sure Drupal would be appropriate. Does it allow public > commentary/editing like a Wiki or does it have more or an edit- >> authorize->publish work flow?yeas, it has very fine grained and mature permission system. udo. -- :: udo waechter - root@zoide.net :: N 52º16''30.5" E 8º3''10.1" :: genuine input for your ears: http://auriculabovinari.de :: your eyes: http://ezag.zoide.net :: your brain: http://zoide.net
hi, On 12.05.2008, at 18:13, Luke Kanies wrote:> > On May 12, 2008, at 8:24 AM, udo waechter wrote: > >> btw.: is RST this? http://docutils.sourceforge.net/rst.html >> If so, I think it is very similar to the textile markup language, >> and could be easily converted to that. > > > Yes, it is. > > It bears some resemblance to textile, but textile is essentially an > html-only markup; it''s never going to be useful for generating PDFs, > for instance. > > I kinda hate textile as a result.generating arbitrary output from pages is a matter of plugins in drupal. creating .pdfs or text (for print) is no problem. If somebody hates textile, he could use various other input formats in drupal. - full html - xhtml - none at all. bye, udo. -- :: udo waechter - root@zoide.net :: N 52º16''30.5" E 8º3''10.1" :: genuine input for your ears: http://auriculabovinari.de :: your eyes: http://ezag.zoide.net :: your brain: http://zoide.net
Throwing my two cents to the discussion, with the cavaet that I have over 5 years experience implementing documentation sites in PmWiki, MediaWiki, TikiWiki, Xaraya, Xoops, Notes Databases/Teamrooms, flat text/html files, and several other popular CMS and wiki systems. I''ve worked on 5 person team documentation sites all the way up to 150+ enterprise system admin team sites and done all manners of migration between various systems. So I think I have something to add to this conversation. On May 8, 9:07 am, James Turnbull <ja...@lovedthanlost.net> wrote:> 1. Move the wiki from Trac to something else. Some options have been > proposed:This idea needs to be weighed *VERY* carefully. These migrations never, EVER go as smoothly as you think, even if you wrote all the documentation on one system and are moving it to another. As mentioned, I''ve done all manners of migrations, and I would only suggest this as a last resort. I won''t even address the merits of the listed options, or bring up any other software, because I consider this to be a bad move.> 2. Restructure the wiki in place on TracThis is the optimal approach. Structure is vital when it comes to documentation, because a proper structure makes information easy to find (even when search functions suck[1]) and more importantly, easy to add or modify. Is there a way to either enable the search function on the wiki *only* for the wiki? Or add a "wiki search" box separate from the entire site search?> 3. Leave the wiki alone - it''s perfect!Clearly this is not the case or there wouldn''t be over a dozen responses to this thread. In fact, the thread would not have been started :-). The documentation does need to be cleaner. I am definitely willing to assist with this. [1] Like Trac, fwiw, TikiWiki''s search always returned more results, poorly formatted, and it was annoying enough to make me design the site to be navigatable rather than searchable. --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com To unsubscribe from this group, send email to puppet-users-unsubscribe@googlegroups.com For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en -~----------~----~----~----~------~----~------~--~---
I vote that jtimberman gets to restructure the Trac Wiki for us! Who is with me?!? :) On a more serious note, I am leaning toward keeping Trac and fixing its small flaws rather than throwing it out and starting over. It already has RST (which some people really like) and the search functionality shouldn''t be too much trouble to fix. At the least we could put a Google search button on the Wiki pages; its not ideal but it would get us over the initial hump. As for the content, could we set up a page that outlines the standards and "force" everyone to abide by those rules? Above all we have to remember its our job to make the Wiki work by editing the content and keeping up with the changes in the platform. Without an active user base no Wiki will work, regardless of the tools used. Later... Richard On May 13, 11:45 am, jtimberman <grumpysm...@gmail.com> wrote:> Throwing my two cents to the discussion, with the cavaet that I have > over 5 years experience implementing documentation sites in PmWiki, > MediaWiki, TikiWiki, Xaraya, Xoops, Notes Databases/Teamrooms, flat > text/html files, and several other popular CMS and wiki systems. I''ve > worked on 5 person team documentation sites all the way up to 150+ > enterprise system admin team sites and done all manners of migration > between various systems. So I think I have something to add to this > conversation. > > On May 8, 9:07 am, James Turnbull <ja...@lovedthanlost.net> wrote: > > > 1. Move the wiki from Trac to something else. Some options have been > > proposed: > > This idea needs to be weighed *VERY* carefully. These migrations > never, EVER go as smoothly as you think, even if you wrote all the > documentation on one system and are moving it to another. As > mentioned, I''ve done all manners of migrations, and I would only > suggest this as a last resort. > > I won''t even address the merits of the listed options, or bring up any > other software, because I consider this to be a bad move. > > > 2. Restructure the wiki in place on Trac > > This is the optimal approach. Structure is vital when it comes to > documentation, because a proper structure makes information easy to > find (even when search functions suck[1]) and more importantly, easy > to add or modify. > > Is there a way to either enable the search function on the wiki *only* > for the wiki? Or add a "wiki search" box separate from the entire site > search? > > > 3. Leave the wiki alone - it''s perfect! > > Clearly this is not the case or there wouldn''t be over a dozen > responses to this thread. In fact, the thread would not have been > started :-). The documentation does need to be cleaner. I am > definitely willing to assist with this. > > [1] Like Trac, fwiw, TikiWiki''s search always returned more results, > poorly formatted, and it was annoying enough to make me design the > site to be navigatable rather than searchable.--~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com To unsubscribe from this group, send email to puppet-users-unsubscribe@googlegroups.com For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en -~----------~----~----~----~------~----~------~--~---
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Richard wrote: | I vote that jtimberman gets to restructure the Trac Wiki for us! Who | is with me?!? :) | Oh me too. I am totally with any plan that involves less work for me. :) Any other volunteers also welcome. I guess my concern around Trac is capabilities. I articulated some broad directions for the documentation overall that I am not sure Trac can address (see initial email). Happy to be corrected if it can. This also ignores any potential bug tracking/project management capabilities that Trac might or might not provide. | On a more serious note, I am leaning toward keeping Trac and fixing | its small flaws rather than throwing it out and starting over. It | already has RST (which some people really like) and the search | functionality shouldn''t be too much trouble to fix. At the least we | could put a Google search button on the Wiki pages; its not ideal but | it would get us over the initial hump. As for the content, could we | set up a page that outlines the standards and "force" everyone to | abide by those rules? | Hard to do with a wiki - in order to control it people need to have read and followed the documentation. You can have to be careful not to set the bar for entry too high and thus dissuade people from editing/creating. But such a document is on my list of things to create. | Above all we have to remember its our job to make the Wiki work by | editing the content and keeping up with the changes in the platform. | Without an active user base no Wiki will work, regardless of the tools | used. | Trying not to blow my own trumpet but I am probably responsible for about 80% of the edits to the wiki. Whilst I''d like to think that a lot of people will jump in past experience suggests otherwise. Happy to be proved wrong though. Regards James Turnbull -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.7 (MingW32) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org iD8DBQFIK4749hTGvAxC30ARAvePAKCRA3suspJVRdyRVvlWfOolHSgLgwCgnvEB vtowC/2O1jJgxhNbqoPdtzY=/ASj -----END PGP SIGNATURE----- --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com To unsubscribe from this group, send email to puppet-users-unsubscribe@googlegroups.com For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en -~----------~----~----~----~------~----~------~--~---
On May 14, 2008, at 8:16 PM, James Turnbull wrote:> Trying not to blow my own trumpet but I am probably responsible for > about 80% of the edits to the wiki. Whilst I''d like to think that a > lot > of people will jump in past experience suggests otherwise. Happy to > be > proved wrong though.To me, this is the main point. The people (or really, mostly ''person'') doing the vast majority of the work on the wiki are finding it wanting. The easiest way to make your point is to show it through action, and James definitely has. If you think it can be made acceptable, it''d be great if you could help make it so. -- Get forgiveness now -- tomorrow you may no longer feel guilty. --------------------------------------------------------------------- Luke Kanies | http://reductivelabs.com | http://madstop.com --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com To unsubscribe from this group, send email to puppet-users-unsubscribe@googlegroups.com For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en -~----------~----~----~----~------~----~------~--~---
On May 14, 7:16 pm, James Turnbull <ja...@lovedthanlost.net> wrote:> > | I vote that jtimberman gets to restructure the Trac Wiki for us! Who > | is with me?!? :) > | > Oh me too. I am totally with any plan that involves less work for me. > :) Any other volunteers also welcome.I''m perfectly okay with this once I have the room on my plate cleared up. I expect a large amount of the time I spend on any Puppet documentation to be done in my own free time, as I expect my boss would rather I help develop *OUR* documentation first :-).> Hard to do with a wiki - in order to control it people need to have read > and followed the documentation. You can have to be careful not to set > the bar for entry too high and thus dissuade people from > editing/creating. But such a document is on my list of things to create.One approach to "enforce" standards is to keep an eye on the update timeline (rss feed ftw) and undo / fix changes that people make that aren''t in the standards. That has worked well in the past for me. On large documentation projects, I''ve gone as far as to train 1-2 people in the standards used and have other people submit plain content, and have the standards ''team'' enter it. However, it can probably be argued that it takes longer to do the formatting to standard than it does to write the documentation. --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com To unsubscribe from this group, send email to puppet-users-unsubscribe@googlegroups.com For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en -~----------~----~----~----~------~----~------~--~---