Re: A GNU Binutils wiki

[Mark Wielaard <mark@klomp.org>]

Hi,

On Wed, Nov 02, 2022 at 02:49:35PM +0000, Nick Clifton via Binutils wrote:
> > Not to be negative but what type of content is going to go in the Wiki?
> 
> Well I am hoping that there will be two types of content:
> 
>  1. Things that will encourage people to contribute to the binutils.
>  2. Information that will help binutils users solve their problems
>     (without having to post questions to the mailing list).
> 
> > Over at RTEMS, I've become quite disillusioned with Wikis for most
> > content. Not being integrated with the source processes, version
> > control, and releases, it can become out of sync and out of date.
> 
> To be fair I am expecting that much of the content will not be that
> sensitive.  Things like the descriptions of what the tools do, how to
> contribute changes, where to ask for help, the history of the project
> and so on.  These are all fairly static.

I think the wiki is nice for these kind of more "social" things than
direct code things. I added a little on the buildbot CI and try
builders: https://sourceware.org/binutils/wiki/Buildbot

> > It's usually much easier to keep documents in any markup system
> > up to date than a wiki.
> 
> Would you feel happier if the text for the wiki was kept in the sources
> and then uploaded to the site on a semi-regular basis ?  (eg when releases
> are made, or once a month, or some other schedule).

However the documentation is maintained it will always be a bit of a
struggle to keep it up to date. The advantage of the wiki is that it
is updated immediately and that non-developers can update it. But for
documentation that is actually about the code it makes sense that only
actual developers can commit it.

Now that we have the buildbot and do a build for every commit of code
we can do the same for the documentation.

How are the current code snapshots created? How is the documentation
uploaded at release time?

We can automate both and publish them on a special buildbot worker
under something like snapshots.sourceware.org/bintuils to keep them
current and so everybody can immediately see how the documentation
looks.

Cheers,

Mark