Re: makedoc syntax (was Re: [AD] Screen destruction documentation update)

[ Thread Index | Date Index | More lists.liballeg.org/allegro-developers Archives ]


Elias wrote:
>Now, ideally, I think both could use the same ._tx source format (not
>the current of course), just one edits it in a text-editor, the other in
>the web-interface. It also would make the patch sending trivial
>(everything is ._tx).
>
Unless there's one central place to make documentation changes, it
would be very challenging to keep things in sync. If an a.cc editor
approves a doc change, but it gets rejected by the Allegro team for
inclusion in the official docs, it would be out of sync from there on
forward.

There will be nothing preventing anyone from subscribing to receive a
list of proposed documentation changes. Basically, the system will
generate a message (probably daily or weekly options) that will notify
the current status of online documentation, such as: pending changes,
applied changes, and new draft pages.

If someone from the Allegro team wanted to monitor it and borrow
changes, that is perfectly fine. Ultimately, I think it could get too
bothersome to do it, because none of the patches would work on
makedoc, considering the online manual is in a very wiki-ish format
and isn't guaranteed to be in sync.

> There are two things I find most important:
>
> 1 Easy editing for developers (at least for me personally, it means an
> offline text editor, and a wiki-like text format)
> 2 Easy editing for users (wiki-like web-interface)
>
There would be nothing preventing you from exporting the online
manual, editting the docs off line, and then submiting the changes to
the site. It would look as if you did it all online. However, I think
anyone with a dedicated Internet connection (who isn't planning on
editing documenation while on the road) will much prefer the online
system if he gives it a fair chance.

On 9/10/05, Evert Glebbeek <eglebbk@xxxxxxxxxx> wrote:
> documentation up to date with changes made. For me, it's simply too
> bothersome and time consuming to try to keep them synchronised if they're
> disjunct.
> 
I don't expect the Allegro team to use the online docs at all if they
want to maintain the makedoc approach. It's not their responsibility
to upkeep an unendorsed manual.

I am totally convinced that it will be a much better system, and that
a lot of people who would never consider touching makedoc will be
eager to help out with the documenation. I've heard the argument that
those people don't exist, but I'm one of them myself. I'd jump at the
chance to edit something online via instant wiki gratification - but
when it comes to open up a huge ._tx file with no word wrapping and a
cryptic syntax, I'll stay away.

I envision scenarios such as: a newbie on a.cc posts a problem
regarding blit(). A veteran helps him out by linking to the manual and
explaining something. Someone (perhaps the same person) then takes it
upon himself to click on the linked blit() function and then click
"edit" and make a clarification or update to the description. Trusted
editors then get notified that there is a pending change. Assuming
it's accepted, it instantly updates the manual and all downloadable
versions of it - without having to wait a few months (or years) for
the next Allegro release. That would *never* happen with an offline
makedoc format. Once people start doing that and seeing themselves get
credited with doc updates, they may just very will start proactively
writing documentation.

I don't want to have a "competing" version of the manual, but I know I
will never convince the Allegro team if I just don't build it and let
it speak for itself. :)

--
Matthew Leverton




Mail converted by MHonArc 2.6.19+ http://listengine.tuxfamily.org/