* Google "Season of Docs" [not found] <8bb78ce0-9b32-7c49-e4aa-ce9f31662627@thingbag.net> @ 2019-03-30 17:17 ` Philip Oakley 2019-03-31 6:41 ` Kapil Jain 2019-03-31 21:49 ` Thomas Gummerer 0 siblings, 2 replies; 5+ messages in thread From: Philip Oakley @ 2019-03-30 17:17 UTC (permalink / raw) To: Git List 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 ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: Google "Season of Docs" 2019-03-30 17:17 ` Google "Season of Docs" Philip Oakley @ 2019-03-31 6:41 ` Kapil Jain 2019-03-31 22:19 ` Philip Oakley 2019-03-31 21:49 ` Thomas Gummerer 1 sibling, 1 reply; 5+ messages in thread From: Kapil Jain @ 2019-03-31 6:41 UTC (permalink / raw) To: Philip Oakley; +Cc: Git List 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 ? ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: Google "Season of Docs" 2019-03-31 6:41 ` Kapil Jain @ 2019-03-31 22:19 ` Philip Oakley 0 siblings, 0 replies; 5+ messages in thread From: Philip Oakley @ 2019-03-31 22:19 UTC (permalink / raw) To: Kapil Jain; +Cc: Git List 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 ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: Google "Season of Docs" 2019-03-30 17:17 ` Google "Season of Docs" Philip Oakley 2019-03-31 6:41 ` Kapil Jain @ 2019-03-31 21:49 ` Thomas Gummerer 2019-04-01 9:05 ` Philip Oakley 1 sibling, 1 reply; 5+ messages in thread From: Thomas Gummerer @ 2019-03-31 21:49 UTC (permalink / raw) To: Philip Oakley; +Cc: Git List 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. ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: Google "Season of Docs" 2019-03-31 21:49 ` Thomas Gummerer @ 2019-04-01 9:05 ` Philip Oakley 0 siblings, 0 replies; 5+ messages in thread From: Philip Oakley @ 2019-04-01 9:05 UTC (permalink / raw) To: Thomas Gummerer; +Cc: Git List 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/ ^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2019-04-01 9:05 UTC | newest] Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- [not found] <8bb78ce0-9b32-7c49-e4aa-ce9f31662627@thingbag.net> 2019-03-30 17:17 ` Google "Season of Docs" Philip Oakley 2019-03-31 6:41 ` Kapil Jain 2019-03-31 22:19 ` Philip Oakley 2019-03-31 21:49 ` Thomas Gummerer 2019-04-01 9:05 ` Philip Oakley
Code repositories for project(s) associated with this public inbox https://80x24.org/mirrors/git.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).