Documentation move
Noah Kantrowitz
official documentation in to the repo. There is a growing problem
with the quality and organization of them, and I think forcing people
to go through the normal patch-review process would help us keep the
docs usable, and would create a visible split between the formal,
reviewed documentation and the community written stuff in the wiki.
What do people think?
--Noah
Eli Carter
Seconded.
It may mean more work for us to pull the good changes from the wiki into the
official source, but I think it would be worthwhile.
Eli
Emmanuel Blot
review all the documentation and a strict peer reviewing of the
documentation to produce official docs ?
Do we have the human resources to move to this model? I have strong
doubts about this point.
We need a clearer documentation model, but moving it to the repository
seems a bit "too strong" from my perspective.
Having two (or more) source of information (official docs, wiki pages
on t.e.o.) is also quite confusing for the end user.
OTOH, I think the first thing to do about the docs is to "branch" it:
one area for Trac 0.10, another area for Trac 0.11 - which means
duplication of info - but we really need to create two areas rather
that to add those "since 0.11" stuff. 0.11 is really different than
0.10, and I agree: t.e.o. is getting more and more confusing each day.
Having docs on the repository could improve the quality of the
documentation, but we might miss hands to update the repository on a
regular basis.
Anyway, whatever the model we choose, we first need to define how we
organize the files/pages first. I can't build a mental picture of
t.e.o. documentation right now. There are several pages to store
similar information (such as TracFaq, trouble shooting guide and the
like)
Cheers,
Manu
--
Manu
Alec Thomas
> > I want to propose (well voice a proposal from Alec) that we move the
> > official documentation in to the repo. There is a growing problem
I really can't take credit for any innovation here, I'm just proposing
we emulate what Chris did for Genshi and Babel:
http://genshi.edgewall.org/#Documentation
http://babel.edgewall.org/#Documentation
Canonical documentation is stored with the source, but trivially exposed
in the Wiki.
Documentation for the different versions of Trac are achieved by simply
including from the appropriate part of the repository.
Of course these projects don't (yet ;)) have the same number of users
as Trac, but it seems like a reasonable model to me regardless.
On 7/28/07, Emmanuel Blot <manu...@gmail.com> wrote:
>
> So if I understand it right, it means that we need people/time to
> review all the documentation and a strict peer reviewing of the
> documentation to produce official docs ?
The initial import of the docs would be no more work than we currently do
when moving the base docs into trunk before a release (ignoring any
reorganisation and cleanup we might like to do as well, of course).
Ongoing I see it being less work. At the moment we spend a not
insignificant amount of time fixing user changes to the Wiki. With the
proposed plan, the Wiki would be for users to "self help", with the
repository for official Trac documentation.
> Do we have the human resources to move to this model? I have strong
> doubts about this point.
In what way?
> We need a clearer documentation model, but moving it to the repository
> seems a bit "too strong" from my perspective.
> Having two (or more) source of information (official docs, wiki pages
> on t.e.o.) is also quite confusing for the end user.
I don't believe this is true.
> OTOH, I think the first thing to do about the docs is to "branch" it:
> one area for Trac 0.10, another area for Trac 0.11 - which means
> duplication of info - but we really need to create two areas rather
> that to add those "since 0.11" stuff. 0.11 is really different than
> 0.10, and I agree: t.e.o. is getting more and more confusing each day.
>
> Having docs on the repository could improve the quality of the
> documentation, but we might miss hands to update the repository on a
> regular basis.
I think this is a matter of training ourselves: "When developer
adds/changes a feature, update documentation as well. Commit.". This
could in fact make documentation better by reducing the cognitive
overhead of having to switch from "coding mode" to "documentation mode".
> Anyway, whatever the model we choose, we first need to define how we
> organize the files/pages first. I can't build a mental picture of
> t.e.o. documentation right now. There are several pages to store
> similar information (such as TracFaq, trouble shooting guide and the
> like)
I'd propose we just use the existing documentation layout in subversion
to start with, and reorganise as we go:
1. Convert current "official" docs into [[Include(/path/)]]
(preferably with different "trees" for each Trac version).
2. Create a documentation landing page "TracDocumentation" with links
to the documentation for different versions. Maybe create links to
some user "self help" pages as well. Maybe the FAQ should be self
help.
For point 1. it might be useful to have a macro installed on TEO to
expose all this documentation with one call:
[[TracDocumentation(/trunk/trac/wiki/default-pages)]]
Or something.
There's another potential opportunity here too: removing the user
visible wart of having all the documentation in their Wiki and timeline.
A request handler could be written to serve Trac documentation instead.
Just a thought.
--
Evolution: Taking care of those too stupid to take care of themselves.
Jeroen Ruigrok van der Werven
>What do people think?
I've been ranting about that a few months ago, if you remember.
So yes, I'm all for it.
--
Jeroen Ruigrok van der Werven <asmodai(-at-)in-nomine.org> / asmodai
イェルーン ラウフロック ヴァン デル ウェルヴェン
http://www.in-nomine.org/ | http://www.rangaku.org/
When Silence cries... Is it what I feel? Or is it what you really long
to be..?
Tim Hatch
> > > official documentation in to the repo. There is a growing problem
>
> I really can't take credit for any innovation here, I'm just proposing
> we emulate what Chris did for Genshi and Babel:
That seems like a reasonably good solution.
> > Do we have the human resources to move to this model? I have strong
> > doubts about this point.
>
> In what way?
I echo this question. I don't know that it's going to take more
effort for sure.
> > OTOH, I think the first thing to do about the docs is to "branch" it:
> > one area for Trac 0.10, another area for Trac 0.11 - which means
> > duplication of info - but we really need to create two areas rather
> > that to add those "since 0.11" stuff. 0.11 is really different than
> > 0.10, and I agree: t.e.o. is getting more and more confusing each day.
Indeed, it's confusing. But we also need to keep in mind how search
engines are going to return docs. If someone searches for
"tracmercurial" and arrives at the wrong version, we need to make it
obvious how to switch to the right version of the docs.
> There's another potential opportunity here too: removing the user
> visible wart of having all the documentation in their Wiki and timeline.
> A request handler could be written to serve Trac documentation instead.
Have you already started any work on this? I'd like to see a proof of
concept before I say this is obviously better than the wiki (because
the wiki currently handles all the linking issues).
Tim
Emmanuel Blot
> effort for sure.
What I meant is that up to now, we faced difficulties to maintain a
coherent and up-to-date documentation. If users are offered both an
"official" documentation and a user-maintained documentation - which
would be both indexed by search engines - , while we do not have the
bandwidth to update the official doc from the user-maintained one, I'm
not sure it will help the users finding their ways in the various doc
sources.
I don't say that moving the doc to the repos is a bad idea, though.
> Indeed, it's confusing. But we also need to keep in mind how search
> engines are going to return docs. If someone searches for
> "tracmercurial" and arrives at the wrong version, we need to make it
> obvious how to switch to the right version of the docs.
Very true.
However I probably miss something important here, but the main source
of the documentation is the online version available from
trac.edgewall.org (whatever the doc is backed up in the repos or in
the SQL db), not the local documentation an admin may - or may not -
install on his server. Many admins simply don't want their project to
be polluted with the wiki pages that come with the default install,
nor install a local Trac project for the sake of having the
documentation available locally. Most of the Trac documentation is
about setting up Trac (i.e. admin doc), not about using it (i.e. user
doc)
At this point, having the doc in the repository may be nice to manage
it (while it really matters for the Trac developers, not for Trac
users/admin) but it may slow down how fast the changes are committed
to the official area, leaving the user with confusing sources of
information.
Again I'm not against moving the doc to the repository, I just have
some questions about how the user will be able to reach the right doc
- and only the one he needs.
--
Manu
solo turn
> review all the documentation and a strict peer reviewing of the
> documentation to produce official docs ?
>
> Do we have the human resources to move to this model? I have strong
> doubts about this point.
therefor manu has a point here. i thought the problem is that nearly
nobody takes the time to fix the 0.11 documentation?
i guess you could invite my contribution by:
1. switching off / fixing this stupid spam protection
saying "max edits is reached" after 10 minutes of work
even if i did not enter one single hyperlink.
2. fixing wiki so subpages get handled in a neat way.
take http://trac.edgewall.org/wiki/0.11/TracGuide:
* hover over the toc and you
get "http://trac.edgewall.org/wiki/0.11WikiFormatting"
* click on upgrade and you end up
at "http://trac.edgewall.org/wiki/TracUpgrade"
which is 0.10 version.
ad quality, you do not mean (1)
http://genshi.edgewall.org/browser/trunk/doc/streams.html, coming from
clicking a link in
http://genshi.edgewall.org/browser/trunk/doc/index.txt, or (2)
http://babel.edgewall.org/wiki/ApiDocs/babel.core (saying: is
generated in a live way, please do not use...)?
tracs very restricted committer model and login model is barely suited
for the code. how long did it take until eli got the right to commit?
and how many patches are included/hidden somewhere in tickets which
nobody can apply? while projects like mercurial gain committers out of
nothing with repositories like crew
(http://selenic.com/mercurial/wiki/index.cgi/DeveloperRepos).
but if you have commit right and are not trapped by spam protection
you do not have problems ... here we say sometimes "its easy to stink
with full trousers" ;)
-solo
tr...@nogga.de
> 2. fixing wiki so subpages get handled in a neat way.
> take http://trac.edgewall.org/wiki/0.11/TracGuide:
> * hover over the toc and you
> get "http://trac.edgewall.org/wiki/0.11WikiFormatting"
> * click on upgrade and you end up
> at "http://trac.edgewall.org/wiki/TracUpgrade"
> which is 0.10 version.
>
A dump question that jumped into my head while reading this: Is it
possible to show a big warning sign on top of the page, if the page is
not in the same sub wiki space as the refereer? The lookup of each
WikiLink is done in the context of the sub wiki. If it is not there a
gloabl lookup is done, e.g searching the parents and the grand parents
and so on. E.g.when clicking on the TracUpgrade in 0.11/TracGuide and
there is no 0.11/TracUpgrade page the user will be redirected to the
global TracUpgrade page with a warning sign and the possibility to
create the 0.11/TracUpgrade page. If the link was intended, the message
box will note the user how he can change the subwiki page with the
correct link syntax.
This would give the best of both worlds:
* clear separation of the subwikis
* automatic linking to the nearest equally named WikiPage
Just a late night thought
Dirk
Noah Kantrowitz
--Noah
Jeroen Ruigrok van der Werven
>Having two (or more) source of information (official docs, wiki pages
>on t.e.o.) is also quite confusing for the end user.
Personally, speaking with a professional technical writing hat on, wiki pages
are one of the worst possible formats to write documentation in.
It is nice for quick notes, highlights, and that sort of thing, but there is
very little that can thus far replace normal well-written documentation for
the simple matter that most wikis fall into the "hyperlink to hell" trap.
--
Jeroen Ruigrok van der Werven <asmodai(-at-)in-nomine.org> / asmodai
イェルーン ラウフロック ヴァン デル ウェルヴェン
http://www.in-nomine.org/ | http://www.rangaku.org/
Sometimes I wonder why are we so blind to face...
Eli Carter
> tracs very restricted committer model and login model is barely suited
> for the code. how long did it take until eli got the right to commit?
A reasonable length of time. Committer rights shouldn't be too exclusively
held, but you do need to wait long enough to see that someone isn't going to
start causing headaches left and right. But that is, as you mention later, a
characteristic of a centralized repository.
> and how many patches are included/hidden somewhere in tickets which
> nobody can apply? while projects like mercurial gain committers out of
> nothing with repositories like crew
> (http://selenic.com/mercurial/wiki/index.cgi/DeveloperRepos).
A distributed model would be helpful for getting wider participation; but it's
a significant change that shouldn't be made lightly. That said, we might be
able to move that direction in phases...
> but if you have commit right and are not trapped by spam protection
> you do not have problems ... here we say sometimes "its easy to stink
> with full trousers" ;)
I've also seen indications that the spam protection has too many false
positives. :(
Eli
Jeroen Ruigrok van der Werven
>A distributed model would be helpful for getting wider participation; but it's
>a significant change that shouldn't be made lightly. That said, we might be
>able to move that direction in phases...
Count my personal vote against giving out committer rights left and right.
Thus far Trac has had a solid vision and a good team to tackle things and the
careful addition of people has only stabilized this more.
It's a myth that adding more people will make things go faster.
--
Jeroen Ruigrok van der Werven <asmodai(-at-)in-nomine.org> / asmodai
イェルーン ラウフロック ヴァン デル ウェルヴェン
http://www.in-nomine.org/ | http://www.rangaku.org/
Praying upon deaf ears...
Christopher Lenz
>> but if you have commit right and are not trapped by spam protection
>> you do not have problems ... here we say sometimes "its easy to stink
>> with full trousers" ;)
>
> I've also seen indications that the spam protection has too many false
> positives. :(
Where? Whenever I look into the spam-filter logs, I see pretty much
all of legitimate submissions going through, and on the other hand
tons of spam being recognized as such.
If there really are disturbingly many false positives, I'm not seeing
any proof in the logs, and would be really interested in hearing
about concrete examples. And not examples from a year ago, mind you,
when false positives were indeed an obvious problem.
Cheers,
Chris
--
Christopher Lenz
cmlenz at gmx.de
http://www.cmlenz.net/