#19 Lack of good documentation

Open
opened 2 years ago by RISCI_ATOM · 7 comments

The libreCMC has had a lack of documentation for most of the project's life due to lack of time and upstream docs being non-free (CC-BY-NC-SA) or tainted with documentation from the same / similar source.

libreCMC documentation needs to be cleanly written and can't be tainted with non-free documentation (all docs should be licensed CC-BY-SA). The reason this is a concern is because vendors who sell devices with libreCMC need to be able to distribute or reuse documentation that libreCMC should be providing.

The libreCMC has had a lack of documentation for most of the project's life due to lack of time and upstream docs being non-free (CC-BY-NC-SA) or tainted with documentation from the same / similar source. libreCMC documentation needs to be cleanly written and can't be tainted with non-free documentation (all docs should be licensed CC-BY-SA). The reason this is a concern is because vendors who sell devices with libreCMC need to be able to distribute or reuse documentation that libreCMC should be providing.

I would like to contribute some docs, what is the most needed docs?

I would like to contribute some docs, what is the most needed docs?

@jonasbits2, a good start is by identifying the things that you find confusing. For example, here's a question that I didn't understand until @jxself explained it to me repeatedly:

What is the difference between "factory" and "sysupgrade" images? When would I use one over the other? I'm still trying to figure out how to express an answer...

@jonasbits2, a good start is by identifying the things that you find confusing. For example, here's a question that I didn't understand until @jxself explained it to me repeatedly: What is the difference between "factory" and "sysupgrade" images? When would I use one over the other? I'm still trying to figure out how to express an answer...
pi31415 commented 2 years ago

Two questions:

Two questions: - How does one edit the wiki? - Is there any reason text can't be copied and pasted from docs like <https://lede-project.org/docs/user-guide/introduction_to_lede_configuration> where it is labeled "CC Attribution-Share Alike 4.0 International"? It would only require about 4 minor edits to convert from LEDE to librecmc.
RISCI_ATOM commented 2 years ago
Collaborator

1) Fork and make a pull request against https://gogs.librecmc.org/libreCMC/libreCMC-wiki

2) The concern is that some LEDE documentation is still tainted with stuff pulled from the OpenWRT wiki (which is licensed CC-NC-BY). I don't want to run the risk of tainting libreCMC with it.

1) Fork and make a pull request against https://gogs.librecmc.org/libreCMC/libreCMC-wiki 2) The concern is that some LEDE documentation is still tainted with stuff pulled from the OpenWRT wiki (which is licensed CC-NC-BY). I don't want to run the risk of tainting libreCMC with it.

As of today openwrt.org shows me that it is licensed under CC-BY-SA 4.0.

As of today openwrt.org shows me that it is licensed under CC-BY-SA 4.0.
lenzj commented 1 week ago

I was considering contributing to documentation regarding supported hardware. It seems that the current information is quite dated and doesn't align with what is available in the releases?

I currently use a WNDR3800 and was researching whether there are faster routers compatible with LibreCMC and ended up buying a used TP-Link WDR4300. Somehow I missed that there are Archer-C7 releases available which probably would have been a better choice. Or are those models not in the "supported" category?

Any suggestions on how I could tackle documentation updates to make the choices easier for new users of LibreCMC or existing users looking to upgrade?

I was considering contributing to documentation regarding [supported hardware](https://gogs.librecmc.org/libreCMC/libreCMC/src/LTS/docs/Supported_Hardware.md). It seems that the current information is quite dated and doesn't align with what is available in the [releases](https://librecmc.org/librecmc/downloads/snapshots/v1.5.1/targets/ath79/generic/)? I currently use a WNDR3800 and was researching whether there are faster routers compatible with LibreCMC and ended up buying a used TP-Link WDR4300. Somehow I missed that there are Archer-C7 releases available which probably would have been a better choice. Or are those models not in the "supported" category? Any suggestions on how I could tackle documentation updates to make the choices easier for new users of LibreCMC or existing users looking to upgrade?
RISCI_ATOM commented 1 week ago
Collaborator

Sadly, the supported hardware list is (mostly) up-to-date. The project is not able to support all of the devices that have images available, for various reasons. In order to get official support from the project, a device must meet the following requirements:

  • libreCMC must be installable from stock firmware, preferably from the provided web-ui.

  • The device can't contain hardware that requires the usage of non-free drivers or blobs.

  • The device's model line can't contain revisions that would not work with libreCMC (ex. v1 works, but v2 or v3 can't be supported). This requirement makes it less confusing and reduces the risk that an unsupported device would purchased.

  • The project must be able to obtain the device for testing. If an issue pops up, then we must be able to replicate it on real hardware.

The devices that are not on the supported list can't meet these requirements, don't have full support, have not been tested or are difficult to obtain.

I currently use a WNDR3800 and was researching whether there are faster routers compatible with LibreCMC and ended up buying a used TP-Link WDR4300. Somehow I missed that there are Archer-C7 releases available which probably would have been a better choice. Or are those models not in the "supported" category?

The Archer C7 v1/v2 is a good example of this issue. The reason that the project provides images is because the non-free wifi module can be replaced. If we added it to the supported list, people might buy it and expect it to work out of the box w/o any modifications.

Any suggestions on how I could tackle documentation updates to make the choices easier for new users of LibreCMC or existing users looking to upgrade?

The main challenge is that we need to make the distinction about what is supported (out of the box) and what could be supported if someone is willing to put the work into it; we need to do it without endorsing devices that contain non-free hardware out of the box.

Sadly, the supported hardware list is (mostly) up-to-date. The project is not able to support all of the devices that have images available, for various reasons. In order to get official support from the project, a device must meet the following requirements: * libreCMC must be installable from stock firmware, preferably from the provided web-ui. * The device can't contain hardware that requires the usage of non-free drivers or blobs. * The device's model line can't contain revisions that would not work with libreCMC (ex. v1 works, but v2 or v3 can't be supported). This requirement makes it less confusing and reduces the risk that an unsupported device would purchased. * The project must be able to obtain the device for testing. If an issue pops up, then we must be able to replicate it on real hardware. The devices that are not on the supported list can't meet these requirements, don't have full support, have not been tested or are difficult to obtain. > I currently use a WNDR3800 and was researching whether there are faster routers compatible with LibreCMC and ended up buying a used TP-Link WDR4300. Somehow I missed that there are Archer-C7 releases available which probably would have been a better choice. Or are those models not in the "supported" category? The Archer C7 v1/v2 is a good example of this issue. The reason that the project provides images is because the non-free wifi module can be replaced. If we added it to the supported list, people might buy it and expect it to work out of the box w/o any modifications. > Any suggestions on how I could tackle documentation updates to make the choices easier for new users of LibreCMC or existing users looking to upgrade? The main challenge is that we need to make the distinction about what is supported (out of the box) and what could be supported if someone is willing to put the work into it; we need to do it without endorsing devices that contain non-free hardware out of the box.
Sign in to join this conversation.
Loading...
Cancel
Save
There is no content yet.