i found that for people that are busy but also need to work and complaint
with alpine linux it's very ilogic that the only way to people get
knowledge about the features of alpine development tools and environment
are a single comment in a pull merge request..

*> you could take a look at the `/usr/bin/newapkbuild` script for now and
search for `cmake`*

the comment above, are a suggestion but are the only documentation, how
could the only documentation will be "searching in the code" that maybe
could be too abstract in most cases! i'm not a xpert english writer but i
made excellent maridb and LAMP focused wiki pages in the alpine wiki, but
only due are common with my debian targets.. but i cannot spend (and of
course most people) time that of course i need to work!

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

the time we spend in understand a script maybe be little in this case but
could be precious for packagers that try to collaborate and have a life
outside..

alpine must have a developer policy that commits of new tools must be made
with minimal documentation included

*i'll not explain something obvious.. 89% alpine linux commits are made by
you Natanael , do you people check what happened to Void? i guess
that's enough explanation! *


Lenz McKAY Gerardo (PICCORO)
http://qgqlochekone.blogspot.com

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

PS: The pdf version is actually better browsable as the online html,
enabling a toc sidebar.
https://mxmanuals.s3.us-east-2.amazonaws.com/user_manual_mx19/mxum.pdf

2020-05-08 12:47 GMT-04:00, Al Pi <alpine@vodafonemail.de>:
> 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

i like that! due take note of the "whose manual start how to read this
manual" that's the reason of the "use cases" wiki pages i created,
easy to read without terminology

alpine linux has many new terminology that not all "linux users" are
familiar (those winbuntu shit that thinks are linux users)

maybe the best are to advertise "you must have real knowledge of linux
before try here"

> When it comes to documentation for users,
> mixing different things side by side together on wiki pages

wikimedia are a shit! i cannot create common portions of pages to
reuse like redmine does.. and use cases are the best option for users!

by example not all the people have usb boot, also not all the users
have a rPi device.. etc etc.. so i try to created a wiki install page
for each case!

its the best for new users! already working for others projects!

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


-- 
Lenz McKAY Gerardo (PICCORO)
http://qgqlochekone.blogspot.com

Hello,

On Friday, May 8, 2020 6:29:32 AM MDT PICCORO McKAY Lenz wrote:
> i found that for people that are busy but also need to work and complaint
> with alpine linux it's very ilogic that the only way to people get
> knowledge about the features of alpine development tools and environment
> are a single comment in a pull merge request..
> 
> *> you could take a look at the `/usr/bin/newapkbuild` script for now and
> search for `cmake`*
> 
> the comment above, are a suggestion but are the only documentation, how
> could the only documentation will be "searching in the code" that maybe
> could be too abstract in most cases! i'm not a xpert english writer but i
> made excellent maridb and LAMP focused wiki pages in the alpine wiki, but
> only due are common with my debian targets.. but i cannot spend (and of
> course most people) time that of course i need to work!
> 
> 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

Actually, there is a work in progress developer's handbook on https://
docs.alpinelinux.org/ but it's nowhere near complete yet.

Ariadne