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

[Pekka Paalanen]

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 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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 811 bytes
Desc: OpenPGP digital signature
URL: <https://lists.freedesktop.org/archives/wayland-devel/attachments/20160822/2d4a00ae/attachment.sig>