Re: Need some reviews, please

[Michael Tremer <michael.tremer@ipfire.org>]

[-- Attachment #1: Type: text/plain, Size: 2560 bytes --]

Hi,

On Tue, 2016-09-13 at 00:24 -0500, R. W. Rodolico wrote:
> When I first decided to pay back some of the benefit I received from
> this project, I realized I do not have the dedication or time to be a
> developer. So, I test and document.

Always welcome, you know that.

> When I first started doing any documentation, I was scared to change
> anything, and I believe I caused the development team more trouble
> fixing my messups than I actually helped. Because of this, I started
> looking more closely at the "how do we document the project" idea.
> 
> I reorganized http://wiki.ipfire.org/projects/docs/start slightly to put
> articles about "How to write articles" in the bottom section, "Wiki
> guideline".
> 
> At Mr. Tremer's suggestion, I then read (kind of), an original document
> at http://wiki.ipfire.org/test. It is in German!

Can we merge all of this into the new doc guidelines and get rid of this old
document?

> NOTE: I do not speak German. I speak three languages; English, Bad
> English and Very, Very Bad Spanish. You'll note that German is not
> listed there at all. Learning to count to 29 on my grandmothers knee
> does not count as speaking German. Nor does 6 weeks of German class in
> college. This was all about Google Translate and guessing. That article
> (in Bad English) is at
> http://wiki.ipfire.org/projects/docs/quick_syntax_overview and
> desperately needs review.

"Bad English" is quite good I think if that means simple and short. This doesn't
have to sound like Shakespear and we have many readers for which English is only
a second language, so the simpler, the better. Technical documentation is
probably never too exciting to read :)

> Finally, I decided we needed some quick guidelines, so I wrote
> http://wiki.ipfire.org/projects/docs/basic_documentation_guidelines.
> Again, this definitely is not a finished project, and it is mainly
> filled with guesses at what our basic guidelines should be. I did try to
> read some of the other articles to see what these guidelines should be,
> but feel free to tell me I'm way off base.
> 
> Feedback??? Please! I have very thick skin, so tons of negative feedback
> will not hurt my feelings. I just want someplace we can send new
> documenters to and say "here, read this if you want to know how we do
> things."

I just read over it very quickly, but I like what I see.

Maybe try dividing it into multiple pages when it becomes longer and to
demonstrate the namespaces :)

Best,
-Michael

> 
> Rod

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 819 bytes --]