This is a combined reply to a number of recent threads. 1) The role of the wiki.
Wikis are great for rapid editing and community contribution, but they (or at least ours) lack the editorial controls and systems to produce high-quality output. I see the role of the wiki going forward as being limited to discussion-oriented topics. A great example is the proposals under TracDev. These exist to be edited frequently and we don't really mind if the occasional typo slips in. The other limitation of our wiki is that we cannot easily "branch" as you would in subversion. This means anything that is tied to particular Trac version generally shouldn't go in the wiki. The wiki is still a good place to sketch things out before they get placed in the real docs, such as with an FAQ, but those pages will need people to watch them more carefully than most others (though we still have the normal checkin process as a gatekeeper). 2) The process for changing docs. Docs are no different than code. If you (a community member) want to change the docs, open a ticket and submit a patch as with anything else. This allows for tight control over what goes in and allows us to be sure we trust what goes in. This is to avoid the problems we have now with things like the platform-specific docs where most were never correct to begin with (doc-rot is a different issue). 3) Sphinx vs. Trac wiki. As we discussed earlier, ReST/Sphinx brings a powerful toolchain with it that we have no equivalent of. Sure we could take the time to clone all of that to work with Trac wiki markup, but I really don't see the point. ReST is not so difficult that a non-programmer couldn't help with things like spotting typos or pointing out bad content. Since we are using the normal patch submission process, the developer committing the patch can always clean up things like incorrect link markup (one of the more annoying parts of ReST) or whatever. 4) What documentation should exist. I think that SeaChange page is a good place to find this out, though the existing wiki is a pretty good corpus to learn from. Even if many of the platform guides are wrong, the fact that someone wrote them is a decent indicator that we should make something less wrong. 5) Ownership. Someone mentioned this before and I entirely agree with it. Especially with the configuration-specific stuff I would like to see someone that actually knows a lot about it to own that document (platforms, DBs, VC backends, etc). 6) Documentation vs. guides I think it would be wise to have a split in the user docs. One side is the traditional documentation. This is just an explanation of what exists and how it works. Guides, on the other hand, are more self-contained and contain things like best-practices and platform-specific tips. Both have value, but there does need to be a clear line between them. Also we should make at least some effort to not duplicate huge amounts of information between the two. How to setup a header logo doesn't need to be written into every platform guide ever. Also this thread should really continue on trac-dev, not trac-users. --Noah --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Trac Users" 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/trac-users?hl=en -~----------~----~----~----~------~----~------~--~---
