OpenWrt Forum Archive

Topic: [wiki] Initiative to improve OpenWrt documentation

The content of this topic has been archived between 7 Feb 2018 and 4 May 2018. Unfortunately there are posts – most likely complete pages – missing.

I'd just like to chime in here. While I am relatively new to this community, I'd like to start my contributions in the Wiki for the time being. The HOWTO documentations are horrible. Grammar is bad, spelling is bad, random capitalization and complete lack of flow in some of the guides.

I'm going to making edits. Feel free to critique and lambaste anything you disagree with.

Thanks h4waii!

Yes, absolutely, thank you h4waii. I'd like to get back into doing this more as we go forward. Is there anything I can do to help folks most?

Eric

Maybe you could show us common mistakes, so that we can learn a few things, I'm probably making all the classic mistakes, and i try to fix them but it's hard to fix something when you still have to figure out the correct way. And thus make new mistakes that still need fixing.  At this point I'm taking a focus on small issues like typo's and details.  Also wondering if there is a need for Dutch translations.  And how to keep a translation in sync with the main wiki.  Maybe only translate pages that are in a more final stage? But how can we know this?

https://wiki.openwrt.org/doc/hardware/port.gpio

in BB
echo "29" > /sys/class/gpio/export
but in CC it seems to be
echo 29 > /sys/class/gpio/export

without the quotes does the old way need to be preserved?

Then this wiki page mainly talks about sending GPIO signals

Also it would be nice to add info on reading a GPIO pin

to activate GPIO14:
echo 14 > /sys/class/gpio/export
to set as input
echo in > /sys/class/gpio/gpio14/direction

and then read the value with:
cat /sys/class/gpio/gpio14/value

output value will be displayed as 0 or 1


Tough it would damage the flow of the document when i dont add this carefully.
I see many wikipages with an odd flow. And also ones that are really good.

My biggest concern is how to add to a page without damaging the work that is already there.
Writing a forum post is one, but improving a wikipage can be daunting even with a simple addition like this.

What is the policy? Just add it, try my best and hope it works out well, or be more careful about it?

I added USB firmware flashing
https://wiki.openwrt.org/toh/gl-inet/gl … _usb_stick

I have not actually tested this yet, as I'm in the middle of a project on my device.
I'm asking other people who own this device to give me feedback, but I also ask here for feedback.

Maybe it's something to add to the template?  Allthough I don't know if other devices also have this option.

Parallel posting to https://forum.openwrt.org/viewtopic.php … 79#p304179

Minimizing FIXMEs in the OpenWrt wiki

We currently have 315 (!) pages in the OpenWrt wiki that contain FIXMEs.
Fixmes are a sign that some information is missing. You can contribute to the wiki by adding the missing information. After the job is done, don't forget to remove the FIXME.

For easier finding of pages that contain FIXMEs, I created a new search page:
https://wiki.openwrt.org/wiki/maintenan … ith_fixmes

We have two big namespaces to work on:

  • howto

  • toh

Plenty of work to do. Your help is appreciated!
Have fun! ;-)

This page is in the list but there doesn't seem to be a Fixme on it
https://wiki.openwrt.org/toh/nexx/wt3020
However there is a Warning, but nothing to be fixed.

I have skimmed trout a few and it would be nice is some FIXME tags had a note on what actually is expected. For instance a note in red font that asks for the information that is missing.

https://wiki.openwrt.org/toh/avm/fritz.box.wlan.7170 does this but still could be better.     FIXME Update current information!
I have a 7170, but I'm not able to guess what current information is missing,

frietpan wrote:

This page is in the list but there doesn't seem to be a Fixme on it
https://wiki.openwrt.org/toh/nexx/wt3020

"**Failsafe mode appears to be broken as of r43977 (fixme)."

OK, it's a small fixme, not a FIXME, but nevertheless.

tmo26 wrote:
frietpan wrote:

This page is in the list but there doesn't seem to be a Fixme on it
https://wiki.openwrt.org/toh/nexx/wt3020

"**Failsafe mode appears to be broken as of r43977 (fixme)."

OK, it's a small fixme, not a FIXME, but nevertheless.


i see, thats in uboot right?  And they do not release the sources of uboot so i wonder if this ever get's fixed.   So then the fix would be to write that in the wiki and remove the fixme?  Once the Uboot gets fixed then the wiki can be updated..
That seems to be a better way to 'fix it' this way we can fix the documentation as being complete instead of creating open ends that can take ages to get fixed. 

This way the fixme list can eventually be sloved.  for those kinds of open ends, AND it becomes more clear to users that some devices better be avoided until the manufacturer complies to the GPL.  And the ones who do their best to comply to the licenses get more credit for doing so. And more people might choose to buy those. So then it's a win win situation.

Actually might it be an idea to set a flag in the ToH for stuff like this?

A GPL compliance column.  When a devise is fully supported and all software (including Uboot) has an open source then it gets a green checkmark. And if it does not comply toe the GPL then a note can be made what needs to be fixed.

This way we have also a better answer to people who keep asking for a recommended router.  It can even be documented in a different way. Now OpenWrt wiki says: "we do not recommend any specific device". This would in the future nicer if devices are recommended that can run OpenWrt fully compliant to GPL.  This can then be a motivation for manufacturers to actually consider to release the sources.  For them it is a marketing flag..

I added a page to the wiki.
Finding guidelines on where to put it has been harder than it should. The least bad tool is the autogenerated sitemap.

I suggest a "Contribute to this wiki" sections should be put on the first page of the wiki, advertising a page with:
- General style guidelines
- Wiki namespaces descriptions, intended use, specific style requirements.

I presume is lack of directives that makes for poorly organised content.

(Last edited by maga on 6 Feb 2016, 23:35)

Hi guys.

I have rearranged the WNDR3700 page. I had already started adding the tabboxes (liking this very much btw) when I noticed richbhanover had done so already at the bottom.

I would like to suggest links to firmware images are provided like this - with a clear but concise distinction between sysupgrade and factory images and links to both:

https://wiki.openwrt.org/toh/netgear/wn … _downloads

I don't know if you pull this from your data template as well but it looks a lot easier on the eye when the links are wrapped in text like in my example. I suppose this has been brought up before, don't know how feasible it is to have [[$url|$text]] parsed in the templates.

Either way, the templates are an excellent starting boilerplate but once info gets specific I personally find it to complicate things (I do understand the need for standardisation though).

Keep up the good work.

Does anyone else experience that the link below:
Custom OpenWrt image with LuCi integrated (all the way at the bottom)

Ends up in a different corner of cyberspace.
DNS issue?

Hi. I am in the process of getting my patches for a new device accepted into LEDE. However, LEDE doesn't have a wiki yet, and I want to get this thing documented.

I have no idea how to wiki. I'm going to check out it, look for some existing template, and add the device and all the info I can.

Any advice on this? It would be great to have a how-to page on this subject.

The discussion might have continued from here.