Re: Need some reviews, please

["R. W. Rodolico" <rodo@dailydata.net>]

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

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1



On 09/13/2016 09:26 AM, Michael Tremer wrote:
> 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.

Yes, I feel very welcome. I want others who are thinking about helping
to understand what I have found out; helping with the documentation
can be very fulfilling also.

> 
>> 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?

Yes. I'll look at it and see if we can't streamline the guidelines.
I'm fairly certain the document I created is fairly close to the
original. As long as no one spots any errors, I'll be happy to remove
the original doc (the German one).

> 
>> 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 :)

Yes, it would be better to split it up. I was doing a quick and dirty
at the time, trying to get it translated as best I could.

I hope to have some time this weekend, and if that is the case, I'll
work on cleaning up the docs namespace a little.


> 
> Best, -Michael
> 
>> 
>> Rod

- -- 
Rod Rodolico
Daily Data, Inc.
POB 140465
Dallas TX 75214-0465
214.827.2170
http://www.dailydata.net
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.12 (GNU/Linux)

iEYEARECAAYFAlfaLxMACgkQuVY3UpYMlTQwPgCfa1hNamiQVbmABn8mwGWn5855
8ZUAn1+NCWexKnOc+YQ6F5an0l2OK61X
=PCsy
-----END PGP SIGNATURE-----