Re: Feedback from downstreams presentation from DX hackfest 2015

On Feb 2, 2015 6:37 AM, "Philip Withnall" <philip tecnocode co uk> wrote:
> On Mon, 2015-02-02 at 12:19 +0100, Olav Vitters wrote:
> > On Mon, Feb 02, 2015 at 08:05:00AM +0000, Philip Withnall wrote:
> > > It was suggested that I send the presentation to DDL, since it might be
> > > of general interest. I haven’t modified it from the hackfest version, so
> > > please let me know if you have any questions.
> >
> > Can we assume that most still needs to be actioned? Also interested what
> > discussions there were during the hackfest to improving this. E.g.
> > Should we maybe reach out to our advisory board? Some things mentioned
> > lack of documentation. So with DX hackfest and documentation at same
> > time I also wonder if there were any possibilities to improve this.
> Some of the items need actioning via bugs, which I will sort out. Some
> of them have already been fixed (either as part of the client work by
> Collabora, or by others in the time since). Some of them are unfixable,
> and can only be used as general guidelines for trying to avoid such
> problems in future (e.g. in new API designs).
> What do you mean by reaching out to the advisory board? Reaching out for
> further feedback from them as downstreams, or reaching out for resources
> to fix such issues? I think the former would be interesting. I’m not
> sure the latter is worth their time, since it’s a very loosely defined
> goal.
> There were some DX–documentation discussions, although I wasn’t involved
> in all of them so I can’t report fully. One interesting discussion came
> up with a set of requirements for any replacement for gtk-doc:
>  1. Do not want to write XML in documentation comments. Too painful, and
>     a steep learning curve.
>  2. No version control program (but wikis’ version control is fine). Too
>     much of a barrier for contribution.
>  3. No waiting for review of documentation changes — post-hoc gives a
>     much lower barrier to contribution instead.
>  4. Instant gratification: documentation changes should be visible
>     instantly, rather than waiting 6 months for a GNOME release before
>     the docs hit
>  5. Documents need to be available offline in Devhelp.
>  6. Devhelp needs to give you documentation for the version of the
>     library you’re using (e.g. in JHBuild), not the version installed on
>     your system, which is invariably outdated.
>  7. Automatically generate documentation from annotations as much as
>     possible (e.g. eliminate ‘Free return value with g_free()’ in favour
>     of (transfer full)).
>  8. Topic-based help which can be reorganised dynamically; eliminate
>     in-order Docbook indexes. Basically the Mallard approach for
>     reference documentation.
>  9. Don’t put big code examples in C comments; move them to separate C
>     files instead, which can be compiled stand-alone. Have a way of
>     limiting what gets rendered in the docs, plus a link to the full
>     source.
> 10. Don’t parse C with regexps; use documentation from GIR files, and
>     allow g-ir-scanner to do the C parsing legwork.

I'm confused. You want both a wiki, and docs embedded in comments? What are you imagining here?

> 11. One page per function, rather than one page containing a
>     loosely-associated jumble of functions (see also: point #8).
> 12. Include documentation for enums which are specific to a particular
>     function in that function’s documentation.
> 13. The system should actually be maintained. (This isn’t a negative
>     against gtk-doc, which is well maintained. It’s a negative against
>     all the other replacements for it which are not.)
> Note that this is a set of requirements for *any* replacement, whether
> it be gtk-doc version 2, or any one of the many replacements people have
> prototyped. We did not discuss a plan for actually writing a new
> documentation tool for API references.
> Ryan, does that sound like everything we discussed? These are typed up
> from my notes, so if anything needs clarification, please say.
> Philip
> _______________________________________________
> desktop-devel-list mailing list
> desktop-devel-list gnome org

[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]