The Secret of Technical Writing

[jim]

The secret of technical writing is
"nobody wants to read."

Practically, docs should be carefully manicured,
highly organized, with established key words and
phrases, and written at a sixth grade reading
level (partly to accommodate readers whose first
language is not English, but also to accommodate
readers who are working late and are tired. Less
is certainly more.

I hope someone can point me to a policy document
for Ubuntu doc processes.



On 7/29/21 4:43 PM, jim wrote:
>
>
> Thank you, Monika,
>
> I briefly read the page you referenced as well
> as the page that inspired this new effort.
>
> What I want to see is a summary of policies for
> documentation management. If there is such a
> thing, please send a link to that.
>
>
>
> On 7/29/21 2:59 PM, Monica Ayhens-Madon wrote:
>> I am so sorry all! Here is the link:
>>
>> https://discourse.ubuntu.com/t/ways-to-improve-documentation/23478/ 
>> <https://discourse.ubuntu.com/t/ways-to-improve-documentation/23478/>
>>
>> Monica
>>
>> On Thu, Jul 29, 2021 at 5:53 PM jim <jim at well.com 
>> <mailto:jim at well.com>> wrote:
>>
>>
>>
>>     Seems there is no link in the first paragraph.
>>     Please send link.
>>     With thanks
>>
>>
>>     On 7/29/21 2:43 PM, Monica Ayhens-Madon wrote:
>>     > Hello, all!
>>     >
>>     > It's definitely not a secret that our documentation is really
>>     outdated in
>>     > places, and updating it has not been easy. The community team,
>>     however,
>>     > wants to help the community not only update the documents, but
>>     update our
>>     > documentation processes as well, as shown in some of the ideas
>>     in this
>>     > Discourse thread.
>>     >
>>     > If this sounds like something you would like to be a part of,
>>     please join
>>     > the discussion linked in the paragraph above, or start a
>>     discussion here.
>>     > We know any fixes won't be easy, but we want to help the
>>     community build
>>     > documentation and processes that are useful, user-centered, and
>>     sustainable!
>>     >
>>     > Cheers,
>>     >
>>     > Monica Ayhens-Madon (she/her)
>>     > Ubuntu Community Representative
>>
>>     --     ubuntu-doc mailing list
>>     ubuntu-doc at lists.ubuntu.com <mailto:ubuntu-doc at lists.ubuntu.com>
>>     https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
>>     <https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc>
>>
>