-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Peter Meier wrote: | actually I'd also prefer to see them solved together, as project/bug | tracking is also _always_ some kind of documentation. And in a project | like puppet I think it is important to have an ongoing process of | documentation which means that it is coupled with the ongoing process | within the project itself.
Agreed. | so what I didn't see yet is, what exactly is really frustrating? I agree | that documentation is rather hard to find and often a bit a mess. It's a combination of (in no particular order): 1. Removing and ensuring redundant material is purged 2. Making it easier for people to find things 3. Make structure and learning intuitive 4. Ensuring ease of update and up to date information 5. Professional look-and-feel 6. Provide structure and content output options to make documentation flexible - i.e. want it as a single HTML page, or a PDF, or in DocBook, or outputted in Sanskrit :) | However I agree with anarcat that this is mainly a problem of a | wiki-culture (which is not always bad, but in this point it might be/is | bad). Agreed - my preferred approach is to retain the ability to add pages and update some pages but move other pages into a read-only with commenting available model al la MySQL's documentation. | So why not have some more wiki-nazis (i liked that word :P ) who would | just refactor the wiki? I think many people just don't have the heart to | move, split, combine, delete, change or whatever a page of someone else. | however I mean it is a wiki, so: just do it! If you think we can find some... I am happy to slice, dice and otherwise dismember the wiki and fairly frequently have. | but I think it is also important that it should be first clear what kind | of features are necessary (bug tracking, scm and so on) and which might | be good. The much more important point in my opinion is: what would be | seen as a good documentation? what would be the good style, what should | a good documentation contain for puppet? nothing that really have been | defined yet. as far as I remember. please correct me if I'm wrong I have some ideas in this area but I might ask Luke to jump in here as first responder. | | So I think what would be nice would be to know first, what you james and | luke (as well all the other) would accept as a good and reasonable | documentation? Clean and clear, preferably marked up as RST, grammatical English (as most would know I am happy to edit and help here so we don't lose good content because English is someone's second language), well laid out - use headings sensibly and consistently, use contents pages for larger documents... Actually this is a damn good question and I'll update the relevant documentation standards on the wiki and post a link to guide people on this. | Actually I like the auto-generated pages from code the most and I would | prefer more of them! Me too. Regards James Turnbull - -- James Turnbull ([EMAIL PROTECTED]) 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/) -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.7 (MingW32) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org iD8DBQFII51e9hTGvAxC30ARAp6KAKCHUvqqrOaP2fv01CmpJqkun5MP7wCeKi1j VmJ6mLLoFkbAMEGHIZLfs/g= =IlNE -----END PGP SIGNATURE----- --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
