Re: Feedback from downstreams presentation from DX hackfest 2015

Hash: SHA1

On 02/02/2015 05:51 PM, Philip Withnall wrote:
> On Mon, 2015-02-02 at 07:55 -0800, Jasper St. Pierre wrote:
>> 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?
> Sorry, I should have explained that more clearly.
> Documentation is generated from C comments as at the moment,
> reformatted, uploaded to, and then some kind of
> online interface can be used to edit the documentation (and possibly add
> comments to it) with instant gratification. That’s what the first few
> points are about.

This was proposed already for GSOC. In a nutshell the idea was that gtk-doc would a markdown editor with extra metadata into the generated html. When editing this would submt patches to bugzilla (as this is our code-review tool). The infrastructure team was against tools submiitting to bugzilla. We could probably also push to special doc-review branches on git. While this sounds all doable, it unfortunately get more complicated. We'd need to show that a doc 'unit' already has pending patches so that new edits won't clash, then engine would need to be able to somehow rebase them one new doc-builds, ...
> There are no requirements covering how these online edits would be fed
> back into the C comments, but presumably that would happen somehow. The
> fact that there are no requirements means nobody in the hackfest
> discussion had strong feelings about how it should be done.
> Philip
> _______________________________________________
> desktop-devel-list mailing list
> desktop-devel-list gnome org

Version: GnuPG v1


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