Google "Season of Docs"

Google "Season of Docs"

[Philip Oakley]

We mentor Summer of Code projects.
Perhaps we should be doing something similar for docs.  Now Google are:

https://opensource.googleblog.com/2019/03/introducing-season-of-docs.html

April 2-23: Open source organizations apply to take part in Season of Docs

My thoughts include:
* There is an expansion in the user base (e.g. 1.5m downloads on 
Windows), with a corresponding shift in focus (application to practice).
-- Are more examples needed, are the basics understood,
* Manuals are no longer printed, so readability assessments should match 
screen formats (maybe).
-- bite-sized chunks
* Developers rarely want to write documentation (it's too obvious to them)
-- if stack-overflow is the go-to source for 'real' users, why not mine 
that source.
-- Our code base has become larger than the average brain-full, maybe 
that (developer education) also could also benefit from some further 
structural documentation.
* Git for Windows: to few developers, large gaps in knowledge, chasing 
both upstream and MS directions of travel, a high hurdle for WinDevs to 
get started,..
-- the wiki could be built upon, anything to get more support..
* git-scm - the book - at least make it easier to find the 'how to help' 
page! (falls between the Github corporate and Open Source stools, or so 
it seems)

does anyone else have pet thoughts..?

Philip
https://www.infoq.com/news/2019/03/google-launches-season-of-docs

Re: Google "Season of Docs"

[Kapil Jain]

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`

> -- 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 ?

Re: Google "Season of Docs"

[Thomas Gummerer]

On 03/30, Philip Oakley wrote:
> We mentor Summer of Code projects.
> Perhaps we should be doing something similar for docs.  Now Google are:

One thing that I think is worth highlighting, that I don't think is
clear from the blog post or this email, is that in contrast to Google
Summer of Code, Season of Docs targets experienced technical writers,
rather than students.  Just leaving this here for anyone that's just
reading this email and/or the blog post.

Re: Google "Season of Docs"

[Philip Oakley]

hi Kapil,
On 31/03/2019 07:41, Kapil Jain wrote:
> 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.
>
>> -- 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

Re: Google "Season of Docs"

[Philip Oakley]

Hi Thomas

On 31/03/2019 22:49, Thomas Gummerer wrote:
> On 03/30, Philip Oakley wrote:
>> We mentor Summer of Code projects.
>> Perhaps we should be doing something similar for docs.  Now Google are:
> One thing that I think is worth highlighting, that I don't think is
> clear from the blog post or this email, is that in contrast to Google
> Summer of Code, Season of Docs targets experienced technical writers,
> rather than students.  Just leaving this here for anyone that's just
> reading this email and/or the blog post.
I had noticed that they were including experienced technical writers, 
hence my hope that maybe we could learn something from them. It's all to 
easy for devs to say that users never read the documentation without 
appreciating that it may not be readable nor understandable from the 
user perspective, an inverse impostor syndrome effect. Perhaps [1] says 
it all ;-)

Philip

[1] https://git-man-page-generator.lokaltog.net/