Re: Re: Style manual.

Sorry, I'm on my cell phone. I have to insert phpdoc@lists.php.net. You mean (shudder) actually do some work? It's so much easier to criticize. :-) Sure, I'll look at it. My favorite style manual is Strunk & White's "Elements of Style." The original was 17 pages. It may be on the Web. Rule 13: "Omit unnecessary words." Stephen King, in "On Writing." advises cutting 20 percent of the words on the first rewrite. Much documentation never gets that first rewrite. That's our job. Suggestions: Write sentences in the active voice and present tense. Don't use the words "very," "will," or "invalid." "Invalid" is particularly bad because it is a cover-up for for thinking. On Jun 16, 2014 3:56 PM, "Maciej Sobaczewski" <sobak@php.net> wrote: > Yes. Programmers temd to write awful, inappropriate documentation. > That's the reason for a documentation team. A group to polish (NOT > re-write) documentation. The docs need to keep the writer's personality, > yet clean up spelling and grammar. If the writer won't agree to this, then > the group conscience makes the decision. > On Jun 16, 2014 3:38 PM, "Maciej Sobaczewski" <sobak@php.net> wrote: > >> Do we have one? >>> >>> >> What do you mean? Style guidelines? >> > Agree, grammar and style in our manual is very inconsistent. > > This is only, currently existing resource: > https://wiki.php.net/doc/howto/styleguide > > However, as I told you yesterday, I'm currently working on new tutorial > for manual contributors and style guideline is one of the topics I have to > cover. You seem to have some serious knowledge about that. Maybe you'd like > to contribute a little? > https://github.com/php/web-doc/blob/master/tutorial/style.md - > here is > the code, if you are interested. > > Regards, > Maciej. > > PS: Use "reply to group" button, please, to keep discussion in public. >