Developer Docs

[Owen Winkler]

I'm making a few edits in the developer documentation section of the
wiki, and I'm wondering if it would be of benefit to mark documenation
meant or developers in a specific way, and if so, how we could do
that.

One thing that might be nice is if there was some kind of central
dev-docs navigation on those pages to return to developer docs. Right
now, there is no clear link from any page dealing with developer
documentation leading back to a central hub of dev docs.

Can someone more familiar with the inner workings of MediaWiki present
some options? Thanks!

Owen

[Scott Merrill]

> One thing that might be nice is if there was some kind of central
> dev-docs navigation on those pages to return to developer docs. Right
> now, there is no clear link from any page dealing with developer
> documentation leading back to a central hub of dev docs.
>
> Can someone more familiar with the inner workings of MediaWiki present
> some options? Thanks!

You'll want to create categories:
http://www.mediawiki.org/wiki/Help:Categories

You can create a "developer" category, and then assign appropriate
pages to that category.

Although before we do that, I'd like to ask: is there a compelling
reason to continue using MediaWiki over Trac's wiki?

[Owen Winkler]

On Jan 13, 2008 8:03 PM, Scott Merrill <ski...@skippy.net> wrote:
>
> You'll want to create categories:
> http://www.mediawiki.org/wiki/Help:Categories
>
> You can create a "developer" category, and then assign appropriate
> pages to that category.

Cool. It looks like using Categories in combination with Templates
(http://www.mediawiki.org/wiki/Help:Templates) will let us put some
navigation on the page along with the category definition.

Owen

[Michael Bishop]

On Jan 13, 8:03 pm, "Scott Merrill" <ski...@skippy.net> wrote:

> Although before we do that, I'd like to ask: is there a compelling
> reason to continue using MediaWiki over Trac's wiki?

Off the top of my head, I'd say A), we've already established the MW,
and getting from that to the manual isn't the most popular task so
migrating to another place will most likely prove a daunting task B),
people are already somewhat familiar with it's location, so moving at
this point might prove confusing, and C), unless Trac wiki uses
exactly the same markup as MW, more volunteers who are wishing to
contribute might already be more familiar with MW, thus a lower
barrier of entry for people looking to give back to the project.
~miklb

[Matthias Bauer]

Owen Winkler wrote:

1. Create a [[Template:target-devs]] and put a neat "<div>This is
targeted primarily at developers</div>[[Category:Developer Docs]]" in it
2. All pages are listed on [[Category:Developer:Docs]].

-M

[Matthias Bauer]

Matthias Bauer wrote:

Oh, wow, I'm late. Anyhow, the others who said the same are right ;)

We could use Trac's Wiki for developer docs and MW for user docs, but
... I don't like Trac's Wikisyntax. There are extensions for MW to
enable linking with trac, iirc.

-M

[Scott Merrill]

> We could use Trac's Wiki for developer docs and MW for user docs, but
> ... I don't like Trac's Wikisyntax. There are extensions for MW to
> enable linking with trac, iirc.

I'm neither for nor against trac's wiki for out purposes; but from a
maintenance and administration point of view, I usually think less is
more. Trac gives us a wiki, it handles logins and access to the
repository -- it seems fairly natural to make use of its facilities
and avoid the more complicated MW footprint.

[Michael Bishop]

But do you not think separating documentation might not foster a
division in the community at some point between user and developer?
As I understand it, trac and the MW logins are in sync.

I'm also worried about transferring documentation to the manual. I
believe theirs a goal to include dev documentation (more so than now)
into the manual. How will we go about converting and keeping up with
two different sources of user generated content into the manual?

In the end however, I'm not really at a point were I can contribute to
that documentation, so ultimately I suppose it should go where ever is
most convenient to those that will be doing the yeoman's work on it.

~miklb

[Owen Winkler]

Michael Bishop wrote:
>
> In the end however, I'm not really at a point were I can contribute to
> that documentation, so ultimately I suppose it should go where ever is
> most convenient to those that will be doing the yeoman's work on it.

Documentation should go where the facilities are of most value to the
reader.

I have no impression that the features provided by Trac are of such
significant value to the documentation authors that it becomes of value
to the reader.

This thread was started based on the idea of aggregating developer docs
by marking somehow. Trac's inability to do this among other useful
MediaWiki features makes the Trac wiki inadequate for documentation.

Owen