See inline below On Tue, Dec 29, 2020, 09:54 ToddAndMargo via perl6-users < perl6-users@perl.org> wrote:
> On 12/29/20 1:12 AM, Richard Hainsworth wrote: > > Hi Richard, > > > > When deciding to write a technical article, the > > VERY FIRST thing you have to do is determine > > your TARGET AUDIENCE. > > > > In a single sentence, please state for me what > > you believe the TARGET AUDIENCE is for the > > documentation. > > > > Would that it were that simple! But since you have some definite ideas > > about what's wrong, why don't you have a go? > > What the target audience? > > Hi Richard, > > What it is would be what you stated previously: > > "Reference is written for a person who already > knows how to program and who uses Raku" > This is taken out of context. I said the Raku community has come to a consensus that DOCUMENTATION should contain both *tutorial* and *reference*. > What I would like it to be is: > > for both new and advanced users > > Standard technical writing: define terms (links work), > start small and work up to advanced. And no showing off. > But Raku documentation could not be 'standard technical writing', if such a thing exists. Raku documentation should be compared to documentation about another newish language, such as Rust or Go, or Haskell. I think it compares well. > > It's clear that you are a member, but what about others? > > "member". That must be a British term. By context, I > presume you mean I am program in Raku. > I meant 'member of an audience'. Does USA English have another term for an individual in an audience? I think not. Brevity by ellipsis is an literary style that assumes an intelligent reader will supply the missing information from the context. You correctly assumed what I implied. Raku documentation uses a similar technique. > > > I use the > > documentation every time I program in Raku (or C or php) > > I always have the documentation pages open when I am > programming too. > > By the way, your statement > "who already knows how to program and who > uses Raku" > > would definitely apply to me and the docs drive me > around the bend (sometimes the actual source code > is easier for me to understand and I have starting > looking at that too), so I would posit that you > should change your statement to > > "Reference is written for a person who already > has an advanced knowledge of and programs in Raku" > > Oh and it does not help that a google search of > raku this and that turns up 1001 hits on pottery. > Actually if I want an answer to a programming question, I would turn to StackOverflow, and Raku there does not give any ceramic references. > > Richard
