Re: Google "Season of Docs"
hi Kapil, On 31/03/2019 07:41, Kapil Jain wrote:
Show 8 quoted lines
> On Sat, Mar 30, 2019 at 10:48 PM Philip Oakley <philipoakley@iee.org> wrote:
>> * Developers rarely want to write documentation (it's too obvious to them)
>> -- Our code base has become larger than the average brain-full, maybe
>> that (developer education) also could also benefit from some further
>> structural documentation.
> by developer documentation you mean, a doc explaining what each function does ?
> agreed, such developer education will help a lot.
> i am currently trying to do that for `pretty.c`
I was especially thinking for that point of architectural descriptions for the code to help new folk (devs) learn about the codebase, rather than it potentially feeling like a bit of an initiation / indoctrination activity. Often the tidbits about the architecture, organisation and coding approaches are buried in the email archive, but are hard to find for the new comer. For example there are various times that one gets say a "Junio explains" email that contains a wealth of information, but unless recognised and book marked at the time, rapidly disappears under the email pile, so finding the right way of improving that part of the documentation would be useful and is something that Technical Authors can guide on.
Show 6 quoted lines
>
>> -- if stack-overflow is the go-to source for 'real' users, why not mine
>> that source.
> this point is unclear, please elaborate.
> I mean stack overflow is searchable already, what kind of mining are
> we talking about ?
Back at an email on the new switch-branch (etc) command [1] it was pointed out that we can discern a many things from the sorts of questions asked [2]. In that case it was about the User Interface (UI) for 'undo'. There are many other issues that crop up that should have been easily answered by our extensive documentation, but even when folk do try to read the manuals they often don't know where to start or when they have found the right nugget. The idea of 'mining' the stack overflow (SO) data is to help with that.
It should also be noted that the manual style is in many ways dated - it was developed back in the 1960s or before, and was in the days of paper reference manuals for those already experienced in the art. We (the folks interested in documentation) possibly need to reflect on whether the approach is enough, or even sufficient, for the modern world. The SO data provides an insight into the questions folk actually ask, and the answers they need - perhaps if we had that support structure in place it would complement the manuals (there isn't even an index for the manuals, nor 'did you mean/want' prompts should folks land on the wrong man page.
We may want to ask if someone has a 'Simplified English' converter (AECMA did a guidance of aerospace/pilot/tech manuals). In the same vein we should also appreciate that as devs, we are by definition poor at user grade documentation, so getting help may improve things.
I was mainly pointing out the opportunity, as I hadn't seen it mentioned elsewhere on the list.
Philip
[1] https://public-inbox.org/git/CACsJy8Dg06DbbSLuuVHKgQUwHXqqVZLjbmkdkN=m=Vx-QeP6zQ@mail.gmail.com/ [2] https://stackoverflow.com/questions/tagged/git?sort=frequent
Philip Oakley