Documentation move

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  
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

--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the
Google Groups "Trac Development" group.
To post to this group, send email to trac-devgooglegroups.com
To unsubscribe from this group, send email to
trac-dev-unsubscribegooglegroups.com
For more options, visit this group at http://
groups.google.com/group/trac-dev?hl=en
-~----------~----~----~----~------~----~------~--~---

On Friday 27 July 2007, Noah Kantrowitz wrote:
> 
> 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  
> 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?

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

--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the
Google Groups "Trac Development" group.
To post to this group, send email to trac-devgooglegroups.com
To unsubscribe from this group, send email to
trac-dev-unsubscribegooglegroups.com
For more options, visit this group at http://
groups.google.com/group/trac-dev?hl=en
-~----------~----~----~----~------~----~------~--~---

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 ?

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


On 7/27/07, Noah Kantrowitz <kantrnrpi.edu> wrote:
>
> 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
> 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
>
> >
>


-- 
Manu

--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the
Google Groups "Trac Development" group.
To post to this group, send email to trac-devgooglegroups.com
To unsubscribe from this group, send email to
trac-dev-unsubscribegooglegroups.com
For more options, visit this group at http://
groups.google.com/group/trac-dev?hl=en
-~----------~----~----~----~------~----~------~--~---

> On 7/27/07, Noah Kantrowitz <kantrnrpi.edu> wrote:
> > 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://gens
hi.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.blotgmail.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.

--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the
Google Groups "Trac Development" group.
To post to this group, send email to trac-devgooglegroups.com
To unsubscribe from this group, send email to
trac-dev-unsubscribegooglegroups.com
For more options, visit this group at http://
groups.google.com/group/trac-dev?hl=en
-~----------~----~----~----~------~----~------~--~---

-On [20070727 20:47], Noah Kantrowitz (kantrnrpi.edu)
wrote:
>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..?

--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the
Google Groups "Trac Development" group.
To post to this group, send email to trac-devgooglegroups.com
To unsubscribe from this group, send email to
trac-dev-unsubscribegooglegroups.com
For more options, visit this group at http://
groups.google.com/group/trac-dev?hl=en
-~----------~----~----~----~------~----~------~--~---

> > > 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:

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


--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the
Google Groups "Trac Development" group.
To post to this group, send email to trac-devgooglegroups.com
To unsubscribe from this group, send email to
trac-dev-unsubscribegooglegroups.com
For more options, visit this group at http://
groups.google.com/group/trac-dev?hl=en
-~----------~----~----~----~------~----~------~--~---

> I echo this question.  I don't know that it's going to
take more
> 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

--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the
Google Groups "Trac Development" group.
To post to this group, send email to trac-devgooglegroups.com
To unsubscribe from this group, send email to
trac-dev-unsubscribegooglegroups.com
For more options, visit this group at http://
groups.google.com/group/trac-dev?hl=en
-~----------~----~----~----~------~----~------~--~---

On 7/28/07, Emmanuel Blot <manu.blotgmail.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 ?
>
> 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.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.ht
ml, coming from
clicking a link in
http://genshi.edgewall.org/browser/trunk/doc/index.txt
, or (2)
htt
p://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/DeveloperR
epos).

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

--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the
Google Groups "Trac Development" group.
To post to this group, send email to trac-devgooglegroups.com
To unsubscribe from this group, send email to
trac-dev-unsubscribegooglegroups.com
For more options, visit this group at http://
groups.google.com/group/trac-dev?hl=en
-~----------~----~----~----~------~----~------~--~---

Hi,

>  2. fixing wiki so subpages get handled in a neat way.
>       take 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

--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the
Google Groups "Trac Development" group.
To post to this group, send email to trac-devgooglegroups.com
To unsubscribe from this group, send email to
trac-dev-unsubscribegooglegroups.com
For more options, visit this group at http://
groups.google.com/group/trac-dev?hl=en
-~----------~----~----~----~------~----~------~--~---

tracnogga.de wrote:
> Hi,
>
>   
>>  2. fixing wiki so subpages get handled in a neat
way.
>>       take 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
>
>   
The HeirWiki plugin has stuff for doing relative links like
that.

--Noah

--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the
Google Groups "Trac Development" group.
To post to this group, send email to trac-devgooglegroups.com
To unsubscribe from this group, send email to
trac-dev-unsubscribegooglegroups.com
For more options, visit this group at http://
groups.google.com/group/trac-dev?hl=en
-~----------~----~----~----~------~----~------~--~---