[RFC wayland-web] docs, web site, logo

[Peter Hutterer]

On Mon, Aug 22, 2016 at 12:37:52PM +0300, Pekka Paalanen wrote:
> On Sat, 20 Aug 2016 11:54:29 +0100
> Daniel Stone <daniel at fooishbar.org> wrote:
> 
> > Hi Yong,
> > 
> > On 19 August 2016 at 20:08, Yong Bakos <junk at humanoriented.com> wrote:
> > > Hi everyone,
> > > This may feel a bit trivial but I would like to get a sense of how some
> > > improvements to the documentation, web site, and logo (!) might be received.
> > >
> > > Would you be strongly opposed to:
> > >
> > > 1) Migrating the docbook-like documentation into doxygen pages
> > >     Take a look at libinput[1] for an example.  
> > 
> > Our biggest problem isn't the format of documentation we have, but the
> > volume of it. I'd rather leave this until someone actively working on
> > producing a bit of documentation said that they felt it hindered them
> > and the change would be good.
> > 
> > > 2) Publishing the doxygen docs on the web site  
> > 
> > This is good and would be really useful. Even better if it's driven
> > out of CI so it's impossible for us to get it wrong.
> > 
> > > 3) A simple, but polished, redesign of the Wayland web site  
> > 
> > I'd be in favour of this; we could definitely do a much better job at
> > communicating information to multiple audiences (end users who need to
> > be redirected; people who need guides on Wayland/Weston, their
> > requirements, and how to build; developers who need guides on its
> > structure, principles, and how to contribute, etc). And I think the
> > first thing to do would be to draw up our audience and what we need to
> > present to them.
> > 
> > > 4) Replacing the W logo with a high quality logo created by a designer  
> > 
> > I think this is easily the lowest-priority issue here. It's not the
> > best, but it certainly works, and it's not really holding us back from
> > progress. It's also something that's relatively well recognised atm.
> 
> I agree with Daniel on all points.
> 
> I recall there is a good chunk of generated documentation that does
> not get published in the web yet. I think it's the generated
> protocol C API. Yes, it mostly just duplicate of the protocol docs
> generated directly from XML, but there would be differences: the C
> API is different on server vs. client side, and also a little
> different from the language-agnostic protocol spec.
> 
> Getting also wayland-protocols docs generated and published with
> appropriate structure would be good. This I would consider the
> first priority of the four points. It should be almost just a
> matter of hooking up Doxygen to run somehow and making a place to
> upload the docs to.

I think it's only the latter. IIRC the doxygen output was pretty much ready
to go for wayland-protocols, divided up into the matching sections, etc.

Cheers,
   Peter

> I wouldn't migrate to yet another doc format without obvious
> benefits or complaints that the current format is hard to write.
> But if we were, maybe thinking about https://readthedocs.org/
> might be a good idea.
> 
> I think Peter was the most recent doing big doc generation reworks,
> maybe he has some ideas which way to go if you need suggestions.
> 
> I'm curious on what you consider low quality on the logo. There is
> an SVG original of it, too. What would we tangibly gain from having
> a new logo made? Is it too easy to confuse with something else?
> 
> 
> Thanks,
> pq