How to edit documentation so that it propagates into the release

[Ryan Ollos]

Hello,

From time to time I am browsing the Trac documentation on Edgewall's
site (1) and I find something that I think I can contribute to.
Usually it is just a clarification or brief addition; a couple of
words, and the sort of thing that make collaborative editing and wikis
so valuable.

My question is, if I edit the documentation on Edgewall, is it
possible that it will propagate to the next release (possibly after
being approved)? Or is it pointless to edit this documentation as the
documentation in the next release will come from another location? If
that is the case, how can I make a minor edit to the documentation in
the case were it is probably overkill to open a ticket?

An example of an edit I would make is, I think 'WikiModule' should be
added to the list of 'default_handler' options for the [trac] section
of trac.ini (2).

I searched for 20 minutes for an answer to this question. It seems
like there should be a brief section on the HowToContribute page,
describing how to contribute edits to the documentation (3). I think
that end users (non-developers) often have a lot to add to the clarity
and details of documentation because they are often approaching with
less detailed technical knowledge than the developers, so it would be
useful to tell people how they can contribute to the documentation.

Thanks,
- Ryan

(1) http://trac.edgewall.org/wiki/TracIni
(2) http://trac.edgewall.org/wiki/TracIni#trac-section
(3) http://trac.edgewall.org/wiki/HowToContribute

[Christian Boos]

Ryan Ollos wrote:
> Hello,
>
> From time to time I am browsing the Trac documentation on Edgewall's
> site (1) and I find something that I think I can contribute to.
> Usually it is just a clarification or brief addition; a couple of
> words, and the sort of thing that make collaborative editing and wikis
> so valuable.
>
> My question is, if I edit the documentation on Edgewall, is it
> possible that it will propagate to the next release (possibly after
> being approved)?

Yes, it will usually propagate to the next release. That was missed for
0.11.5, but there's a reminder ticket for 0.11.6 about that, so this
time I won't forget ;-)

> Or is it pointless to edit this documentation as the
> documentation in the next release will come from another location? If
> that is the case, how can I make a minor edit to the documentation in
> the case were it is probably overkill to open a ticket?
>
> An example of an edit I would make is, I think 'WikiModule' should be
> added to the list of 'default_handler' options for the [trac] section
> of trac.ini (2).
>

TracIni is a bit special in this respect, as the bulk of its content is
generated by the [[TracIni()]] macro.
Therefore, we have a [TracIni#Discussion] section, where edit
suggestions can be made, or alternatively you can send us a patch on
Trac-dev modifying the docstring in the code.

> I searched for 20 minutes for an answer to this question. It seems
> like there should be a brief section on the HowToContribute page,
> describing how to contribute edits to the documentation (3). I think
> that end users (non-developers) often have a lot to add to the clarity
> and details of documentation because they are often approaching with
> less detailed technical knowledge than the developers, so it would be
> useful to tell people how they can contribute to the documentation.
>

Indeed. Thanks for the suggestion!
(http://trac.edgewall.org/wiki/HowToContribute?version=13)

-- Christian

[RJOllos]

On Aug 23, 11:23 pm, Christian Boos <cb...@neuf.fr> wrote:
> Indeed. Thanks for the suggestion!
> (http://trac.edgewall.org/wiki/HowToContribute?version=13)

Thank you for the timely information. It almost seems like it would
be worthwhile to edit the Help/Guide link in the meta navigation bar
in my Trac instance to point to Edgewall's documentation. I just
started using Trac and I haven't upgraded it yet, but I assume that
any edits I make to the documentation on my Trac instance would be
overwritten in an upgrade (or at least require a possibly time
consuming merge?).

- Ryan

[Christian Boos]

RJOllos wrote:
> On Aug 23, 11:23 pm, Christian Boos <cb...@neuf.fr> wrote:
>
>> Indeed. Thanks for the suggestion!
>> (http://trac.edgewall.org/wiki/HowToContribute?version=13)
>>
>
> Thank you for the timely information. It almost seems like it would
> be worthwhile to edit the Help/Guide link in the meta navigation bar
> in my Trac instance to point to Edgewall's documentation.

That's a possible enhancement, see discussions in:
- http://trac.edgewall.org/ticket/3386
- http://trac.edgewall.org/ticket/2656 (though the
http://trac.edgewall.org/wiki/TracDev/Proposals/NewHelp doesn't talk
about redirecting to a reference site)

> I just
> started using Trac and I haven't upgraded it yet, but I assume that
> any edits I make to the documentation on my Trac instance would be
> overwritten in an upgrade (or at least require a possibly time
> consuming merge?).
>

No, local changes are detected and the modified pages won't get
overwritten during a 'wiki upgrade'. But then, you have no easy way to
do the merging, other than doing a 'wiki export', merge externally and
re-import.

-- Christian