Dev't documentation for Archiva and MRM-1025

[Brett Porter <br...@apache.org>]

Hi,

I know we currently have some developer notes in the wiki, but trying to edit documents in Confluence drives me a little batty and I like to link straight into the javadocs, so I started documenting the MRM-1025 branch here: http://svn.apache.org/repos/asf/archiva/branches/MRM-1025/archiva-modules/src/site/apt/

For documentation in general - what would others prefer? Should we continue to use Confluence (and I can move these across), or would you like to continue these?

I'd appreciate some review of the docs even at this early stage to see if it is starting to make some sense. The next step is to move the content-model.txt and existing wiki page into the Metadata document and add more information, and then to fill in the sequencing information about the repository APIs. Finally, I need to add some documentation of the tasks remaining to get it to production quality.

I intend to propose this for trunk after these are done, so please take a look through the code changes if you get a chance. I don't want this to be a 'code bomb' nobody understands :)

Cheers,
Brett

--
Brett Porter
brett@apache.org
http://brettporter.wordpress.com/

Re: Dev't documentation for Archiva and MRM-1025

[Deng Ching <oc...@apache.org>]

On Mon, Feb 15, 2010 at 12:57 PM, Brett Porter <br...@apache.org> wrote:

>
> On 11/02/2010, at 6:21 PM, Deng Ching wrote:
>
> > For documentation in general - what would others prefer? Should we
> continue
> >> to use Confluence (and I can move these across), or would you like to
> >> continue these?
> >>
> >
> > I prefer the wiki for proposals and development docs, but I'm also fine
> with
> > incorporating it to the site. My only condition is that they are together
> in
> > one place and not scattered in different locations..
>
> Agreed, and also that wherever we put them makes sure they don't get left
> out of date :)
>

+1


>
> What is behind your preference for the wiki? My main reason for wanting to
> use APT was for offline editing and keeping history in subversion, as well
> as it giving a slight encouragement for writing good Javadocs. But it is
> certainly more time consuming to build and view than in Confluence.
>

I like the formatting in the wiki and also being able to preview my changes,
I guess I'm just used to that :) Using the APT is fine for me too as it has
it's own advantages like when working offline as you've pointed out :)


>
> I finished doing what I was planning to for now anyway, and is published
> here: http://archiva.apache.org/ref/1.4-SNAPSHOT/
>

It's looking good :)

-Deng


>
> >> I intend to propose this for trunk after these are done, so please take
> a
> >> look through the code changes if you get a chance. I don't want this to
> be a
> >> 'code bomb' nobody understands :)
> >>
> >
> > I attempted to take look at the branch earlier this year but got
> > side-tracked with other things. Sorry about that.. I'll find some time to
> go
> > over the branch in the next few days :)
>
> Let me know if you need any pointers. I found some of the audit log tests
> are not passing so I may not have re-implemented it consistently. I'll take
> a further look before proposing a merge.
>
> - Brett
>
> --
> Brett Porter
> brett@apache.org
> http://brettporter.wordpress.com/
>
>
>
>
>

Re: Dev't documentation for Archiva and MRM-1025

[Brett Porter <br...@apache.org>]

On 11/02/2010, at 6:21 PM, Deng Ching wrote:

> For documentation in general - what would others prefer? Should we continue
>> to use Confluence (and I can move these across), or would you like to
>> continue these?
>> 
> 
> I prefer the wiki for proposals and development docs, but I'm also fine with
> incorporating it to the site. My only condition is that they are together in
> one place and not scattered in different locations..

Agreed, and also that wherever we put them makes sure they don't get left out of date :)

What is behind your preference for the wiki? My main reason for wanting to use APT was for offline editing and keeping history in subversion, as well as it giving a slight encouragement for writing good Javadocs. But it is certainly more time consuming to build and view than in Confluence.

I finished doing what I was planning to for now anyway, and is published here: http://archiva.apache.org/ref/1.4-SNAPSHOT/

>> I intend to propose this for trunk after these are done, so please take a
>> look through the code changes if you get a chance. I don't want this to be a
>> 'code bomb' nobody understands :)
>> 
> 
> I attempted to take look at the branch earlier this year but got
> side-tracked with other things. Sorry about that.. I'll find some time to go
> over the branch in the next few days :)

Let me know if you need any pointers. I found some of the audit log tests are not passing so I may not have re-implemented it consistently. I'll take a further look before proposing a merge.

- Brett

--
Brett Porter
brett@apache.org
http://brettporter.wordpress.com/

Re: Dev't documentation for Archiva and MRM-1025

[Deng Ching <oc...@apache.org>]

On Thu, Feb 11, 2010 at 1:42 PM, Brett Porter <br...@apache.org> wrote:

> Hi,
>
> I know we currently have some developer notes in the wiki, but trying to
> edit documents in Confluence drives me a little batty and I like to link
> straight into the javadocs, so I started documenting the MRM-1025 branch
> here:
> http://svn.apache.org/repos/asf/archiva/branches/MRM-1025/archiva-modules/src/site/apt/
>

For documentation in general - what would others prefer? Should we continue
> to use Confluence (and I can move these across), or would you like to
> continue these?
>

I prefer the wiki for proposals and development docs, but I'm also fine with
incorporating it to the site. My only condition is that they are together in
one place and not scattered in different locations..


>
> I'd appreciate some review of the docs even at this early stage to see if
> it is starting to make some sense. The next step is to move the
> content-model.txt and existing wiki page into the Metadata document and add
> more information, and then to fill in the sequencing information about the
> repository APIs. Finally, I need to add some documentation of the tasks
> remaining to get it to production quality.
>
> I intend to propose this for trunk after these are done, so please take a
> look through the code changes if you get a chance. I don't want this to be a
> 'code bomb' nobody understands :)
>

I attempted to take look at the branch earlier this year but got
side-tracked with other things. Sorry about that.. I'll find some time to go
over the branch in the next few days :)

Thanks,
Deng