On Mon, Aug 22, 2016 at 12:37:52PM +0300, Pekka Paalanen wrote: > On Sat, 20 Aug 2016 11:54:29 +0100 > Daniel Stone <[email protected]> wrote: > > > Hi Yong, > > > > On 19 August 2016 at 20:08, Yong Bakos <[email protected]> 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 _______________________________________________ wayland-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/wayland-devel
