{"thread":{"id":"50844","subject":"Google \"Season of Docs\"","startedAt":"2019-03-30T17:17:53Z","lastAt":"2019-04-01T09:05:48Z","messageCount":5,"participants":["Philip Oakley","Kapil Jain","Thomas Gummerer"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"372806","messageId":"572677cc-eef3-345b-e970-cd6cc80e8e96@iee.org","threadId":"50844","inReplyTo":"8bb78ce0-9b32-7c49-e4aa-ce9f31662627@thingbag.net","subject":"Google \"Season of Docs\"","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2019-03-30T17:17:51Z","receivedAt":"2019-03-30T17:17:53Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"We mentor Summer of Code projects.\nPerhaps we should be doing something similar for docs.  Now Google are:\n\nhttps://opensource.googleblog.com/2019/03/introducing-season-of-docs.html\n\nApril 2-23: Open source organizations apply to take part in Season of Docs\n\nMy thoughts include:\n* There is an expansion in the user base (e.g. 1.5m downloads on \nWindows), with a corresponding shift in focus (application to practice).\n-- Are more examples needed, are the basics understood,\n* Manuals are no longer printed, so readability assessments should match \nscreen formats (maybe).\n-- bite-sized chunks\n* Developers rarely want to write documentation (it's too obvious to them)\n-- if stack-overflow is the go-to source for 'real' users, why not mine \nthat source.\n-- Our code base has become larger than the average brain-full, maybe \nthat (developer education) also could also benefit from some further \nstructural documentation.\n* Git for Windows: to few developers, large gaps in knowledge, chasing \nboth upstream and MS directions of travel, a high hurdle for WinDevs to \nget started,..\n-- the wiki could be built upon, anything to get more support..\n* git-scm - the book - at least make it easier to find the 'how to help' \npage! (falls between the Github corporate and Open Source stools, or so \nit seems)\n\ndoes anyone else have pet thoughts..?\n\nPhilip\nhttps://www.infoq.com/news/2019/03/google-launches-season-of-docs\n"},{"id":"372826","messageId":"CAMknYEP2m7fJ9o5dybEibmMwJJ9-wMStThwU0YN6f_QZzK=z=w@mail.gmail.com","threadId":"50844","inReplyTo":"572677cc-eef3-345b-e970-cd6cc80e8e96@iee.org","subject":"Re: Google \"Season of Docs\"","fromName":"Kapil Jain","fromEmail":"jkapil.cs@gmail.com","sentAt":"2019-03-31T06:41:38Z","receivedAt":"2019-03-31T06:43:39Z","isPatch":false,"sender":{"key":"jkapil.cs@gmail.com","avatar":null},"body":"On Sat, Mar 30, 2019 at 10:48 PM Philip Oakley <philipoakley@iee.org> wrote:\n>\n> * Developers rarely want to write documentation (it's too obvious to them)\n> -- Our code base has become larger than the average brain-full, maybe\n> that (developer education) also could also benefit from some further\n> structural documentation.\n\nby developer documentation you mean, a doc explaining what each function does ?\nagreed, such developer education will help a lot.\ni am currently trying to do that for `pretty.c`\n\n> -- if stack-overflow is the go-to source for 'real' users, why not mine\n> that source.\n\nthis point is unclear, please elaborate.\nI mean stack overflow is searchable already, what kind of mining are\nwe talking about ?\n"},{"id":"372845","messageId":"20190331214900.GX32487@hank.intra.tgummerer.com","threadId":"50844","inReplyTo":"572677cc-eef3-345b-e970-cd6cc80e8e96@iee.org","subject":"Re: Google \"Season of Docs\"","fromName":"Thomas Gummerer","fromEmail":"t.gummerer@gmail.com","sentAt":"2019-03-31T21:49:00Z","receivedAt":"2019-03-31T21:49:07Z","isPatch":false,"sender":{"key":"t.gummerer@gmail.com","avatar":"https://avatars.githubusercontent.com/u/191004?v=4"},"body":"On 03/30, Philip Oakley wrote:\n> We mentor Summer of Code projects.\n> Perhaps we should be doing something similar for docs.  Now Google are:\n\nOne thing that I think is worth highlighting, that I don't think is\nclear from the blog post or this email, is that in contrast to Google\nSummer of Code, Season of Docs targets experienced technical writers,\nrather than students.  Just leaving this here for anyone that's just\nreading this email and/or the blog post.\n"},{"id":"372848","messageId":"70eeea8b-230c-1f33-f52d-db0e69870a76@iee.org","threadId":"50844","inReplyTo":"CAMknYEP2m7fJ9o5dybEibmMwJJ9-wMStThwU0YN6f_QZzK=z=w@mail.gmail.com","subject":"Re: Google \"Season of Docs\"","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2019-03-31T22:19:20Z","receivedAt":"2019-03-31T22:19:23Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"hi Kapil,\nOn 31/03/2019 07:41, Kapil Jain wrote:\n> On Sat, Mar 30, 2019 at 10:48 PM Philip Oakley <philipoakley@iee.org> wrote:\n>> * Developers rarely want to write documentation (it's too obvious to them)\n>> -- Our code base has become larger than the average brain-full, maybe\n>> that (developer education) also could also benefit from some further\n>> structural documentation.\n> by developer documentation you mean, a doc explaining what each function does ?\n> agreed, such developer education will help a lot.\n> i am currently trying to do that for `pretty.c`\nI was especially thinking for that point of architectural descriptions \nfor the code to help new folk (devs) learn about the codebase, rather \nthan it potentially feeling like a bit of an initiation / indoctrination \nactivity. Often the tidbits about the architecture, organisation and \ncoding approaches are buried in the email archive, but are hard to find \nfor the new comer. For example there are various times that one gets say \na \"Junio explains\" email that contains a wealth of information, but \nunless recognised and book marked at the time, rapidly disappears under \nthe email pile, so finding the right way of improving that part of the \ndocumentation would be useful and is something that Technical Authors \ncan guide on.\n>\n>> -- if stack-overflow is the go-to source for 'real' users, why not mine\n>> that source.\n> this point is unclear, please elaborate.\n> I mean stack overflow is searchable already, what kind of mining are\n> we talking about ?\nBack at an email on the new switch-branch (etc) command [1] it was \npointed out that we can discern a many things from the sorts of \nquestions asked [2]. In that case it was about the User Interface (UI) \nfor 'undo'. There are many other issues that crop up that should have \nbeen easily answered by our extensive documentation, but even when folk \ndo try to read the manuals they often don't know where to start or when \nthey have found the right nugget. The idea of 'mining' the stack \noverflow (SO) data is to help with that.\n\nIt should also be noted that the manual style is in many ways dated - it \nwas developed back in the 1960s or before, and was in the days of paper \nreference manuals for those already experienced in the art. We (the \nfolks interested in documentation) possibly need to reflect on whether \nthe approach is enough, or even sufficient, for the modern world. The SO \ndata provides an insight into the questions folk actually ask, and the \nanswers they need - perhaps if we had that support structure in place it \nwould complement the manuals (there isn't even an index for the manuals, \nnor 'did you mean/want' prompts should folks land on the wrong man page.\n\nWe may want to ask if someone has a 'Simplified English' converter \n(AECMA did a guidance of aerospace/pilot/tech manuals). In the same vein \nwe should also appreciate that as devs, we are by definition poor at \nuser grade documentation, so getting help may improve things.\n\nI was mainly pointing out the opportunity, as I hadn't seen it mentioned \nelsewhere on the list.\n\nPhilip\n\n[1] \nhttps://public-inbox.org/git/CACsJy8Dg06DbbSLuuVHKgQUwHXqqVZLjbmkdkN=m=Vx-QeP6zQ@mail.gmail.com/\n[2] https://stackoverflow.com/questions/tagged/git?sort=frequent\n\n"},{"id":"372860","messageId":"4eefb159-c219-0936-12de-e0c5844c3815@iee.org","threadId":"50844","inReplyTo":"20190331214900.GX32487@hank.intra.tgummerer.com","subject":"Re: Google \"Season of Docs\"","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2019-04-01T09:05:47Z","receivedAt":"2019-04-01T09:05:48Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Hi Thomas\n\nOn 31/03/2019 22:49, Thomas Gummerer wrote:\n> On 03/30, Philip Oakley wrote:\n>> We mentor Summer of Code projects.\n>> Perhaps we should be doing something similar for docs.  Now Google are:\n> One thing that I think is worth highlighting, that I don't think is\n> clear from the blog post or this email, is that in contrast to Google\n> Summer of Code, Season of Docs targets experienced technical writers,\n> rather than students.  Just leaving this here for anyone that's just\n> reading this email and/or the blog post.\nI had noticed that they were including experienced technical writers, \nhence my hope that maybe we could learn something from them. It's all to \neasy for devs to say that users never read the documentation without \nappreciating that it may not be readable nor understandable from the \nuser perspective, an inverse impostor syndrome effect. Perhaps [1] says \nit all ;-)\n\nPhilip\n\n[1] https://git-man-page-generator.lokaltog.net/\n\n\n"}]}