Lance Hendrix wrote: > ... > I must admit I am a little confused with regards to the wiki and the > *.rst files. I followed the conversation yesterday in the (hijacked (my > apologies)) thread on "Trac [Recipes]" and gathered that the consensus > seems to be to continue to provide end user based documentation in > (trac) wiki (this seems reasonable to me), but that developer > documentation should be maintained in the *.rst files (also seems > reasonable); however, what about the developer documentation that is > currently on the wiki? Should this be deprecated and only provide > enough information to allow a developer to get access to the sources > (location of svn repo and directions on which "set" of code to checkout) > and then point them to the *.rst or should there be more info in the > wiki? What is the plan for use of the *.rst files, that is, will they > be published or how will they be incorporated into the project? > > Apologies for all the questions, but I also want to ensure that I don't > go in a direction that is contrary to where you guys are headed and I > don't have enough experience on the project IMHO to really understand > the nuances of these issues as yet, so I tend to ask more than a few > questions.
No problem, the fact is that this is still in the making. When I was talking about using Sphinx for the developer guide, I was actually more thinking about the documentation for the API, where using such a tool is really necessary. Sphinx is quite superior to other similar tools, IMO, as you can better blend the API doc extracted from the source with contextual information and overviews (see the autodoc module [1]). Tim started to document the testing infrastructure in doc/dev, and I followed-up on that, but it's not clear cut yet what's best documented in the Wiki and what's best done close to the source. This also depends on the preferences of the document writer: if Tim had chosen to document the testing infrastructure in more details below TracDev/FunctionalTests, that would have been good for me as well. Btw, looking below TracDev/, there are lots of documents that obviously don't belong to a developer guide (all the Branches/ and Proposals/ pages). Others, like the overviews and the thematic guides could fit quite well there and so might be ported one day. The real problem so far was simply that we didn't have that much man power, and few people actually contributing content or reviewing existing documentation. The burden of maintaining a comprehensive set of documentation for Trac is so important that I think this can only be a community effort. That's one of the reasons why I think that it's not good to move away from wiki-based documentation for the admin and user guide, as it's not realistic to expect Trac users to contribute documentation in the .rst format. For the developer guide, we (the even much smaller Trac developer community) could eventually manage to maintain it in .rst, using Sphinx. Even in that perspective, the wiki and the TracDev/ hierarchy can still be used as an useful staging area for sketching the initial documents. > An appropriate answer might be "grow a set, take ownership, > and get it done" which I can do, but again, I don't want to make > assumptions based on my lack of experience and history with this project > that go contrary to the direction or "spirit" of the project. So you'll > have to let me know when the questions become too much and that I should > just take ownership and "get it done". > As I initially suggested, you can for example take the useful role of the "candid" and list the areas which badly need documentation and the questions that come to mind when you get started as a Trac developer... A TracDev/GettingStarted page would be nice (but as you create it, you get to name it ;-) ). Documenting the documentation process is also an interesting exercise. We need to lead people to that developer guide, either to explain how to build it by themselves or how to get pre-built copies. -- Christian [1] - http://sphinx.pocoo.org/ext/autodoc.html --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Trac Development" 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-dev?hl=en -~----------~----~----~----~------~----~------~--~---
