On May 19, 7:25 pm, Matt Good <[EMAIL PROTECTED]> wrote:
> I think it's useful to continue discussing ways to improve Trac's
> value as a documentation tool, but that shouldn't stop Noah & others'
> momentum on rewriting the documentation.
>
> Noah's efforts with Sphinx push us in the right direction for how we
> want to distribute the documentation, which is a separate issue from
> how we maintain it. Distributions should include a standalone set of
> documentation in HTML and/or PDF formats and be provided inside the
> application within a new Help module so that they're available even
> when the Wiki has been disabled.
>
> I also hope we can agree that the current free-for-all editing of the
> documentation in the t.e.o Wiki has become unsuitable for maintaining
> well-written docs. Moving them into the source tree with a more
> formal patch acceptance process should help that, so let's let Noah
> continue his current work and start a new discussion for how to
> improve Trac to the point where it's suitable for maintaining the docs
> at some point in the future.
Moving to using the repos as master for documentation is a conclusion
that I think is agreed by all in earlier discussions and earlier in
the thread. As for standalone documentation, it does seem like Sphinx
is a good choice - and of course, any effort to review and improve the
content is most welcome. Reusing help pages for internal rendering and
standalone documentation is surely what we would want.
The objection I would like to raise at this stage is how this initial
proof-of-concept is committed to trunk. Having created a newhelp
branch (with proposal) and tried an approach to solving it from the
Trac side with flexibility for help page providers of any kind, I do
think Noah shortcuts a process of refinement and issue resolving that
is nowhere near finished. The new pages are committed as fresh pages
without history, they are committed to a 'doc' directory that is
outside the package that gets installed (and won't be available for
internal help), the rst markup expects Sphinx to be insalled and
produces countless errors when using plain trac rst mimeview
rendering, and issues like localization of help pages is not at all
considered.
We all agree that the docs need fixing, and a number of people are
eager to get it done. I would however prefer that this happened
outside the trunk for the time being so that we can arrive at a full
working solution for all documentation before exposing it in trunk.
:::simon
https://www.coderesort.com
--~--~---------~--~----~------------~-------~--~----~
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
-~----------~----~----~----~------~----~------~--~---
