* Re: [gentoo-soc] Weekly report 07/30
2018-07-29 15:36 ` Brian Dolbec
@ 2018-07-29 18:30 ` Andrew Savchenko
2018-07-30 2:18 ` Pengcheng Xu
1 sibling, 0 replies; 7+ messages in thread
From: Andrew Savchenko @ 2018-07-29 18:30 UTC (permalink / raw
To: gentoo-soc
[-- Attachment #1: Type: text/plain, Size: 2484 bytes --]
Hi!
On Sun, 29 Jul 2018 08:36:14 -0700 Brian Dolbec wrote:
> > While I am not directly involved with gsoc this year... I can't help
> > but to respond here.
> >
> > Reports like this were not acceptable in past years.
> >
> > Just showing a link to a report is not enough.
> >
> > A PROPER report here should include enough info to give the reader an
> > idea if they want to follow the link and get all the details.
> >
> > While I don't expect a 3 page essay, you should summarize what was
> > done in brief, but clear writing. The link to the full detailed
> > report at the end.
>
> I should have followed the link before responding...
>
> The link contents is no more than a brief summary. I didn't do a word
> count, but, I think my previous reply was about the same size... So
> how hard would it have been to copy/paste that text into an email...
>
> But I still find that report lacking for a detailed report. You should
> have included some details of what was done for the automatic setup.
>
> Also, why are your user guides just in a blog? Shouldn't the user guides
> be added to the Gentoo wiki? Blog guide info I would think would only
> be for brief preliminary help info for mentors and other actively
> interested persons. So as the project progressed, they could keep up
> to date with the code. But the real documentation should in my
> opinion be put somewhere central like our Gentoo wiki.
Brian, looks like you missed our workflow. Weekly e-mail reports
are just pointers to the work done this week and documented in the
blog.
The blog entry itself is exactly what you described as "you should
summarize what was done in brief, but clear writing. The link to
the full detailed report at the end." It contains clear summary
with each paragraph linked to the detailed technical or
workflow description. Just follow the links on the blog page:
https://jsteward.moe/category/gsoc-2018.html
(the first link is broken now by some typo and will be fixed).
As for documenting in the wiki, please see previous week's report:
https://jsteward.moe/weekly-report-0723.html
So moving essential parts of the blog posts to the wiki is on the
plan.
But frankly having the job done and documentation written is more
important than bikeshedding about where the docs must be located.
IMHO Wiki is not the best place for them, for one of the reasons ask
williamh why.
Best regards,
Andrew Savchenko
[-- Attachment #2: Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [gentoo-soc] Weekly report 07/30
2018-07-29 15:36 ` Brian Dolbec
2018-07-29 18:30 ` Andrew Savchenko
@ 2018-07-30 2:18 ` Pengcheng Xu
1 sibling, 0 replies; 7+ messages in thread
From: Pengcheng Xu @ 2018-07-30 2:18 UTC (permalink / raw
To: gentoo-soc
Hi Brian,
2018-07-29 23:36 GMT+08:00 Brian Dolbec <dolsen@gentoo.org>:
> On Sun, 29 Jul 2018 08:20:01 -0700
> Brian Dolbec <dolsen@gentoo.org> wrote:
>
>> On Sun, 29 Jul 2018 21:40:30 +0800
>> Pengcheng Xu <i@jsteward.moe> wrote:
>>
>> > Hi all,
>> >
>> > Last week's report is available now. Link:
>> >
>> > https://jsteward.moe/weekly-report-0730.html
>> >
>> > Thanks!
>> >
>>
>> While I am not directly involved with gsoc this year... I can't help
>> but to respond here.
>>
>> Reports like this were not acceptable in past years.
>>
>> Just showing a link to a report is not enough.
>>
>> A PROPER report here should include enough info to give the reader an
>> idea if they want to follow the link and get all the details.
>>
>> While I don't expect a 3 page essay, you should summarize what was
>> done in brief, but clear writing. The link to the full detailed
>> report at the end.
>
> I should have followed the link before responding...
>
> The link contents is no more than a brief summary. I didn't do a word
> count, but, I think my previous reply was about the same size... So
> how hard would it have been to copy/paste that text into an email...
My GSoC weekly report workflow had been like that throughout the project: full
reports, be it long or short, stays on my blog. When the report is
short, the email
usually contains just a link, and the report holds links as well as
descriptions of
each separated topic. Sometimes the descriptions are omitted as the
titles clearly
express what the articles are about.
>
> But I still find that report lacking for a detailed report. You should
> have included some details of what was done for the automatic setup.
Sorry for the overly-concise README for the sharkbait-setup
repository. I updated
the README and added a link to the blog article when the work is first
produced (detailed
steps without any kind of script automation).
>
> Also, why are your user guides just in a blog? Shouldn't the user guides
> be added to the Gentoo wiki? Blog guide info I would think would only
> be for brief preliminary help info for mentors and other actively
> interested persons. So as the project progressed, they could keep up
> to date with the code. But the real documentation should in my
> opinion be put somewhere central like our Gentoo wiki.
There are two reasons that I first write my articles on my blog:
1. I am not familiar with the markup language used in MediaWiki; I
usually write in MarkDown
instead. Switching over to a new Markup language disrupts the
process of writing and is
time-consuming. I plan to use pandoc to convert MarkDown to
MediaWiki and post on Gentoo
Wiki instead of directly writing the guides on the Wiki.
2. IMHO a consistent place where all information can be found is
important. My blog about
the project contains too many details that people won't care, so
not everything is suitable to
be on the Wiki. That's why I've chosen to scrub the articles and
pick important ones and post
them on the Wiki, not directly writing everything on the Wiki.
Thanks!
--
Pengcheng Xu
i@jsteward.moe
^ permalink raw reply [flat|nested] 7+ messages in thread