hi Kapil,
On 31/03/2019 07:41, Kapil Jain wrote:
On Sat, Mar 30, 2019 at 10:48 PM Philip Oakley <philipoakley@xxxxxxx> 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.
-- 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@xxxxxxxxxxxxxx/
[2] https://stackoverflow.com/questions/tagged/git?sort=frequent
