[Nut-upsdev] NUT Website and similar documentation content needs help [WAS: Re: [networkupstools/nut] docs/FAQ.txt... (PR #1200)]

[Jim Klimov]

Hello, and thanks for asking :)

For NUT currently, website refresh is a manual process. There is a
`Makefile` driven automation for that now, but so far humans look over it
and tweak because not always not everything works well to make it a github
or similar CI action.

Historically the NUT web-site was documenting the latest release, to match
what people see delivered by packaging. In our case, it is now 2.7.4 which
is too many years behind master branch. There is a plan "in the back of the
mind" to make the main site follow master-branch development of its sources
(nut, nut-ddl, nut-website... repos) - maybe automatically one day - and
generate static sub-sites for fixed releases.

Currently it is a mixed bag, mostly refreshing HCL/DDL pages and the index
with news and footer links, with careful git merging after site
regeneration (so it stays matching "almost last release" with a few things
from master). And IIRC there was an out-of-git issue with "Koenig"/"König"
path names/symlinks for one device series in HCL that was problematic for
quick automation.

All that said, community help with the content would be very much welcome -
there are a lot of gems (text and screenshots) for documentation
improvements in the github issue tracker. Over past weekends I've
classified many (but not all yet) historic entries, including those with
info that would be useful in Git and website eventually as
https://github.com/networkupstools/nut/labels/documentation - PRs to port
those bits of info would be great! Or maybe use the github Wiki instead...
anyhow, those discoveries about getting things to work on varied platforms,
device specs, vendor-provided MIB and HID tables, etc. are effectively lost
when they are just comments hidden in a closed issue or PR discussion.

Similarly, sadly there is an even larger backlog of HCL and DDL updates -
https://github.com/networkupstools/nut/labels/HCL and
https://github.com/networkupstools/nut/labels/DDL - with core team efforts
focused on getting codebase into shape for a release, these reports were
neglected and piled up for too long (and maybe more are lurking in the
mailing list archives). Converting those data submissions into PRs, and
maybe finding ways to automate that (actionable how-to could be a good
start, and self-service github template pages to submit the reports), would
be a big step forward in practice, and needs just time to figure out the
puzzle pieces spread across existing docs.

So, if someone wonders how to spend days off on winter holidays (any other
time in the year would be good too ;) ) - here's your chance to make a real
and useful difference!

Jim

On Mon, Nov 29, 2021 at 5:43 PM Helmut K. C. Tessarek <
notifications at github.com> wrote:

> @jimklimov <https://github.com/jimklimov> out of curiosity... when are
> the html pages refreshed? I am just asking because other projects just use
> a git hub action after a PR has been merged.
>
> —
> You are receiving this because you were mentioned.
> Reply to this email directly, view it on GitHub
> <https://github.com/networkupstools/nut/pull/1200#issuecomment-981813155>,
> or unsubscribe
> <https://github.com/notifications/unsubscribe-auth/AAMPTFH3ME3ADM7FFQIJCGTUOOUUHANCNFSM5ITJEXLA>
> .
> Triage notifications on the go with GitHub Mobile for iOS
> <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675>
> or Android
> <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>.
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://alioth-lists.debian.net/pipermail/nut-upsdev/attachments/20211201/f70dcf07/attachment.htm>