Date: Fri, 8 May 2020 18:47:11 +0200 (CEST)
From: Al Pi <alpine@vodafonemail.de>
To: PICCORO McKAY Lenz <mckaygerhard@gmail.com>,
	alpine-user <alpine-user@lists.alpinelinux.org>
Message-ID: <1906580709.96391.1588956432516@mail.vodafone.de>
In-Reply-To: <CALci+FSVjg3rR7xfhh73QsmVHqvc+NzYrQ2Okw7WFvA_VtPYzw@mail.gmail.com>
References: <CALci+FSVjg3rR7xfhh73QsmVHqvc+NzYrQ2Okw7WFvA_VtPYzw@mail.gmail.com>
Subject: Re: lack of alpine policy of development tools, cuse lack of time
 for new collaborations
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Importance: Medium

Hello,

this seems like a nice documentation writing stance,
to keep in mind:
(by a positive documentation example)
https://mxmanuals.s3.us-east-2.amazonaws.com/user_manual_mx16/mxum.html#toc-Subsection-1.2

PICCORO McKAY Lenz <mckaygerhard@gmail.com> hat am 8. Mai 2020
um 14:29 geschrieben:
>> you could take a look at the `/usr/bin/newapkbuild`
>> script for now and search for `cmake` if developer put
> minimal documentation, rest of people can contribute
> more and enhanced that documentation.. but without any tips.
> we can not doing nothing more serious

Not sure, but I think packagers may better be familiar
with make stuff, so easily get the details from the source.

Seems like a "less (but organized) is more" thing.

When it comes to documentation for users,
mixing different things side by side together on wiki pages
seems also hard to maintain, as it is to read, with 
redundancy even worse. That may be why organized sections
that are kept short, and separate, as in the mxmanual
example above are so well browseable (in the manual-browser
preinstalled on the systems!, that havs a table of contents
navigation on the left side), in whichever context that's needed
by the reader.

I find the alpine "Install" page organization has improved,
but I'm not sure if some of the further things are still 
relevant. For example, if setting up apk cache is suggested
automatically, by setup-alpine if a device is found?

With a good structure, that resembles the scripts and
tools, documenting changes could possibly be a simple
thing for devs to check/update/remove. (Even generating a
changelog from taged wiki edits maybe?)
Maybe the wiki could also show a TOC on a side bar, for 
faster navigation.

Kind Regards,
-Al