Random but related ideas to contribute: Tags are great, but IMHO what really makes them useful is some sort of faceted navigation where you can search for multiple boolean tags simultaneously or in sequence (i.e. refine your search). I think this should be a part of the Trac system, and would really help find things in docs. e.g. search for tags matching all(Apache, authentication, fcgi) and any (linux, osX).
Also while I admire the wiki format and love wikipedia, I think it is becoming the hammer that is turning all web content into nails. I guess the thing I miss the most is a true page hierarchy. It would be nice to be able to more easily create containers for sets of related documents. Also, if the containers can contain links, then documents can show up in multiple places. I guess links can do that too. Cheers, Ari Noah Kantrowitz wrote: > 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 > > > > > -- /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\ Ariel I Balter, Ph.D. Postdoc Biological Monitoring/Modeling Fundamental and Computational Sciences Directorate Pacific Northwest National Laboratory Mail: PO Box 999, MS P7-58,Richland, WA 99352 Shipping: 790 6th Street, MS P7-58, Richland, WA 99354 Tel: 509-376-7605 Cell: 509-713-0087 [email protected] www.arielbalter.com www.pnl.gov --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
begin:vcard fn:Ariel Balter, PhD n:Balter;Ariel email;internet:[email protected] tel;home:812-332-2721 tel;cell:812-219-4558 x-mozilla-html:TRUE url:http://arielbalter.com version:2.1 end:vcard
