[DISCUSS] How do I crossreference source and wiki?

[Donal Lafferty <do...@citrix.com>]

Is there a way to cross reference source and corresponding descriptions in the wiki?

Newcomers rely heavily on the wiki to figure out what is going on.  When the wiki falls out of date, it is a real struggle to find out what happened.  Just look at today's mailing list posts. :)

If there were a breadcrumb trail that pointed out which wiki's had to be updated, we'd avoid a lot of support emails and reduce onboarding time.

DL

RE: [DISCUSS] How do I crossreference source and wiki?

[Alex Huang <Al...@citrix.com>]

Is there any standard practices that we can follow?  It sounds like a great idea but how do you keep information fresh and don't end up with broken links as things move around (or move completely to another site like CloudStack wiki has)?

--Alex

> -----Original Message-----
> From: Chip Childers [mailto:chip.childers@sungard.com]
> Sent: Wednesday, October 24, 2012 2:41 PM
> To: cloudstack-dev@incubator.apache.org
> Cc: Matthew Morrissey
> Subject: Re: [DISCUSS] How do I crossreference source and wiki?
> 
> Not really...  it's a little bit of a struggle right now.
> 
> Matt (cc'ed) and I were talking about something similar just the other day.
> Matt is going to start writing some unit tests (we've got that happening over
> on the junit-test branch), and wanted to know if it would make sense to start
> to add more comments in the code.
> 
> Perhaps we should start describing the purpose of files, and pointing to
> relevant design pages on the wiki, within source comments?
> 
> -chip
> 
> 
> On Wed, Oct 24, 2012 at 5:30 PM, Donal Lafferty <do...@citrix.com>
> wrote:
> > Is there a way to cross reference source and corresponding descriptions in
> the wiki?
> >
> > Newcomers rely heavily on the wiki to figure out what is going on.
> > When the wiki falls out of date, it is a real struggle to find out
> > what happened.  Just look at today's mailing list posts. :)
> >
> > If there were a breadcrumb trail that pointed out which wiki's had to be
> updated, we'd avoid a lot of support emails and reduce onboarding time.
> >
> > DL

Re: [DISCUSS] How do I crossreference source and wiki?

[Chip Childers <ch...@sungard.com>]

Not really...  it's a little bit of a struggle right now.

Matt (cc'ed) and I were talking about something similar just the other
day.  Matt is going to start writing some unit tests (we've got that
happening over on the junit-test branch), and wanted to know if it
would make sense to start to add more comments in the code.

Perhaps we should start describing the purpose of files, and pointing
to relevant design pages on the wiki, within source comments?

-chip


On Wed, Oct 24, 2012 at 5:30 PM, Donal Lafferty
<do...@citrix.com> wrote:
> Is there a way to cross reference source and corresponding descriptions in the wiki?
>
> Newcomers rely heavily on the wiki to figure out what is going on.  When the wiki falls out of date, it is a real struggle to find out what happened.  Just look at today's mailing list posts. :)
>
> If there were a breadcrumb trail that pointed out which wiki's had to be updated, we'd avoid a lot of support emails and reduce onboarding time.
>
> DL