Don't feel bad about not spending time on the documentation. The work that you both have done so far is critically important, and thus far, wasn't even visible to anyone who wasn't looking hard. (Besides, you can't write documentation for a process that we don't fully understand - I would say that we've only come to that point in the last week or so...)

Now our task is to create a comprehensive guide to how we want people to add new routers. This includes finalizing the Technical Detail template, creating a similar Device Details template, and a final form for the new ToH (which will probably have some instructions on it...)

I don't think we should look at the Bureaucracy plugin now - it's a new piece of technical work that could take us weeks to get working the way we want. (Or not - but I still think it would be a distraction from getting the new ToH published.) Besides, there won't be too many new routers added to the ToH while we're figuring out how the Bureaucracy plugin works.

Finally, I encourage you to update the demowiki page with any improvements you have. Thanks.

Hey guys, I'm back. It's unusually hot here, therefore forgive me the lack of activity during the past days.

I see that there's the need to see the bureaucracy plugin in action.
I created a sample page in the demowiki (after installing the plugin, hehe), but thats only alpha stage.

Seeing only that alpha stage, I'd say that it's easier for the user to create an empty template page first, and then edit that empty page afterwards with the custom editor (data plugin builtin)

The bureaucracy plugin provides the raw fields, without comments.
The data plugin editor additionally shows the very helpful comments.

I take it as my task to find a way to easily create new dataentry pages, the one or the other way.

(Last edited by tmo26 on 5 Jul 2015, 20:53)

I already thought about this in the past. Totally agree!

I think we should just not worry too much about this. After all, it is not so many new devices being created, and most likely quite experienced people will add them early in the process. We can also have a forum topic where we help people to create new devices. It has happened several times that I have encouraged people to add/correct information to the wiki, but nothing happens.

Agree. Keep the "create new dataentries" as a background task.

In the demowiki, I saved back the status before richb edits (let's start modifying step by step).
What I want to see: The "Usage" Section with the "Creating new entries " and "Editing existing entries" subsections.

From here on, we can start to move explanatory content to a separate page, in order to keep the template (which needs to be renamed btw, to fit to the openwrt wiki structure) clean and as a template.

And of course, introduce more changes step by step.

@richb: It's good to have you here. You have a different point of view. That's good

Please have a look at the DIR-505 Techdata page in the demowiki: I added drop-down functionality for some fields. (EDIT: You need to edit the dataentry via the LEFT edit button below the box to see the dropdowns)
One more step towards easier creation of new dataentries

What do you think about the dropdowns?

Note: This requires some updates in
a) the template -> already done in the demowiki -> to be done in the openwrt wiki
b) the datapages -> to be done $sometime or $now, how you like

(Last edited by tmo26 on 6 Jul 2015, 20:01)

@richb: Your deletion of the () for the example values and your request to simplify the creation of new dataentries made me think, also triggered by the dropdowns mentioned above.

Why triggered by the dropdowns?
The dropdowns are self explanatory and show you what is expected.
Dropdowns make some comments and example values unnecessary, e.g. yesno values like serial, vlan; or like modem (i.e. predefined comma separated list of valid values. Definition is done in the dokuwiki admin area).

1) Now if we start with a completely empty copy of the template, we see ... almost nothing of the dataentry when viewed as normal wiki page (i.e. not in the wikisource).
Reason: Fields with no value are not shown by the dataplugin, when viewing the normal wikipage. However, those empty fields will be shown in the editor.

Seeing almost nothing of the dataentry is bad. The user needs at least a slight hint. -> Include at least Brand = (EXAMPLE) in the otherwise empty template.
This way, the dataentry box will show at least "Brand: (EXAMPLE)" -> hint, what to do next -> "Edit the box showing Brand: (EXAMPLE)"

Only when the user edits the dataentry via the editor (not via pageedit), he will see the full dataentry with all fields.

-> Turns out, that completely empty template does not really help the user in estimating what to do next. No good look&feel.

2) Since the above empty template has issues, example values are needed in the template to show all available fields already in normal page view (i.e. not in pageedit mode).

3) Users do not remove example values, if they don't know what to enter instead. -> Example values without any marking will stay there forever, or until someone verifies it (which may take long).

4) Example / Bogus values must be marked somehow -> add () around them.

5) Coming back to the dropdowns from above: No example value needed -> No confusion if values are to be entered with or without () :-)

To close the loop from the beginning and to summarize:

Simplification of creation of new dataentries
- by reducing number of example values in ()
- by introducing dropdowns for selected fields (clickable ¿, no need to enter it manually:)
- by telling the users more exactly what to do with the values in () -> to be done

Further simplification: No "create new page, then copy&paste,..." etc. any more.
Instead, click a button, enter brand, model, version -> new page in correct namespace created automatically -> edit further via the dataentry editor.

This is a bit different compared to the method I was talking about in the past (bureaucracy plugin).
I have been playing around with bureaucracy, and although it offers some nice functionality (dropdowns), it lacks some of it in other areas (no comments shown). This makes me think of bureaucracy as only second best.

IMHO currently best in terms of functionality and ease of use: A dataentry page, filled with example values. Still to do: Creation of new page 'with a click' only. I've seen some plugins around for this purpose -> should be doable.

To close the loop from the beginning and to summarize once more:
Simplification of creation of new dataentries
- OLD: via bureaucracy plugin
- NEW: via (tbd)-plugin + template filled with example values in ()

You see, your stone-throwing made me think, which lead to a new idea on how to proceed.
Keep on throwing those stones! ;-)

P.S.: If this posting seems too long and confused, I blame it on the high temperatures %-)

(Last edited by tmo26 on 6 Jul 2015, 22:07)

I've been away, but you've all been working.

Now that the ToH-generation machinery is in place, my primary goal is to make this self-sustaining. To do that, we need to give people enough information to "do it right" when they add a router to the wiki.

- On a macro scale, that means we need the introductory material I put at the top of the demowiki page. It may not belong there (I'm not sure where it goes), but it needs to be visible at the point that someone realizes, "Hey, I want to add a router to the ToH!"

- On a micro scale, I'm trying to guess (and that's all it is) what the template should contain so that people will "do it right". In the current example, putting (...) around bogus entries will tell *us* that people haven't changed it. But my first thought (a couple months ago) when I saw the parentheses was that these were *required*, and that I dare not leave them out because "something might break".

So this is a hard design process, and we'll probably make mistakes. But we shouldn't let that concern paralyze us. Let's pick one choice and watch carefully how people use it.

PS I prefer to call it "throwing a rock in the pond" - it makes waves, but nobody gets hurt :-)

@richb / zo0ok: I've installed the folded plugin in the demowiki. See an example on the dataentry_template in the demowiki -> see the usage section.

It's not meant to be permanently this way. It's quick & dirty

I find the plugin useful (I use it myself in my dokuwiki) for keeping pages compact while also keeping the content. If someone is interested in the details -> click on it, there you have it.

Edit: Installed also hidden plugin -> same functionality, different look.
Example: dataentry_template in the demowiki -> see the usage section.

Which one do you like best?

(Last edited by tmo26 on 7 Jul 2015, 20:26)

I know, it was supposed to be a background task... however, I couldn't resist in checking out ways to easily create new dataentry pages.

I came back to the bureaucracy plugin, but only for the pure creation of the page and filling in Brand, Model and Version into the page. The rest of the dataentry filling should be done via the dataentry editor (It's so comfortable, provides comments and dropdowns).

Please try it yourself in the demowiki: -> Create new dataentry page 2
Please also see the resulting page, which includes the explanatory sections "folded" [Edit]up[/Edit], in order not to overload the user with information.

Comments please!

(Last edited by tmo26 on 8 Jul 2015, 18:09)

@zo0ok:

The creation of new dataentry pages implies some changes to the brand-naming you apply: Since the namespace and filename are derived from the user input "Brand", which may be D-Link or TP-Link, we need the '-' inbetween. Otherwise we would have the pages created by you in dlink/, whereas the automatic created pages would be in d-link/.

Changes needed for dropdowns in the dataeditor: Adding of special datatypes
Supported Since Rel_release
Supported Current Rel_release
Target_target
Flash MB_flash
RAM MB_ram
Modem_modem
VLAN_yesno
WLAN Stds_wlanstds
Serial_yesno
JTAG_yesno
LED count_led
Button count_button
Bootloader_bootloader

Can you update the datapages accordingly, please?

Further suggestion: Split "Wired ports" in "Wired ports 100M" + "Wired ports Gbit" -> enables dropdowns also for these fields -> More clicking, less typing, less inconsistent data.

OK...

The '-' in Brands need to be preserved when I create the foldername and filename for the dataentry file?
And if there are '-' in the model as well?

And I change all the above mentioned "Column name"-labels as you suggest.

The spit of Wired Ports... something in me worries about how to handle 10Mbit, 10Gbit, fibre connections, and other things I dont know about. I will think about it.

I have been busy and I feel a bit behind. I have tried to submit a patch to openwrt-dev... that is hard for an amateur. But it is good to see that you think and write and work Cant complain about the heat though... as we say in Sweden... "Summer is the best day of the year".

Templates on the page http://wiki.openwrt.org/doc/howto/adding_to_toh are missing.  If I want to add a new device where is the actual Router Page template located?

(Last edited by rayknight on 8 Jul 2015, 23:11)

I'm glad you're working to make the Wiki better - we are too. And yes, at this moment, you have stumbled upon a page that we haven't had a chance to create.

If I were adding a router today, I would probably start with a nice page as a template for a new router. I'm especially fond of the TP-Link Archer C7 page. It is clear about the information you should provide, and that counts for a lot.  It's at: http://wiki.openwrt.org/toh/tp-link/tl-wdr7500

And after you add your router, would you let us know its details page so we can update our info? Thanks!

WTF? Where has the device template in http://wiki.openwrt.org/meta/templates gone???
It WAS there!

Edit: The page template_device has been edited by some dumbass and then deteled.

@admins: Please revert the changes and re-insert revision http://wiki.openwrt.org/meta/template_d … 1434026007 (the last one before any changes are done).

We can avoid this accidential deletion of template pages by
- making template pages read only
- by usage of bureaucracy new-page-creation process (as shown in the demowiki for creating new dataentry pages)

(Last edited by tmo26 on 9 Jul 2015, 05:22)

Yes

Good point. Yes, in the model too.

Updated:
https://dl.dropboxusercontent.com/u/906 … index.html
https://dl.dropboxusercontent.com/u/906 … ikitxt.tgz

You had replaced Flash MBs with Flash MB_flash.
To me it seems like problems with 16Mb + 1024Mb NAND.
So I gave you Flash MBs_flashs (inspired by WLAN Stds_wlanstds), I expect I may need to change these again in the future.

The wired ports... how about:
- Uplink Port (10M, 100M, GBit, DSL, Other, None)
- Switch Port count (0-24)
- Switch Port speed (N/A, 10M, 100M, Gbit)
I guess the names will need to be thought more about, but how about the concept?

Not bad. More clicking, less typing.

How are others doing it? -> https://wikidevi.com/wiki/Netgear_WNDR3700
LAN speed: 10/100/1000
LAN ports: 4
WAN ports: 1

I'm indifferent in how to exactly name these.

Edit: More about the new datapages in about 1h. Import is running (longer than expected, due to some pebkac...).

(Last edited by tmo26 on 9 Jul 2015, 19:11)

Thanks for the update, quick as always!

Some remarks:
- LED count_led is missing the _led
- WLAN Stds_wlanstds               : b/g/n -> needs to be changed to b, g, n (with or without spaces, doesn't matter)

Wait with the creation of a new dataset. THere will be at least one more change.

You are absolutely right, but now it's getting tricky
I will change the config so that the NANDs are also available.

Edit: "16Mb + 1024Mb NAND" -> needs to be changed to "16Mb, 1024Mb NAND", if we want the Flash MB to be a multiselectable field.

Lets see how it looks!

(Last edited by tmo26 on 9 Jul 2015, 20:52)

The missing change:

Detachable Antennas_ -> Detachable Antennas_detachantenna

Ready for a new round of data.

(Last edited by tmo26 on 9 Jul 2015, 20:56)

@richb: Please take a look at template_dataentry_reb
What do you think about the new page creation process?
IMHO it can't be much easier

I might have removed too much of the old page creation process explanation, so feel free to reimplement what you think is necessary for the new process.

And BTW: I added some folding underneath the dataentry block. OK?

Should be "Flash MB_flashs"

Yes, it's_s driving me crazy too %-)

(Last edited by tmo26 on 9 Jul 2015, 23:04)

Last one for today: toh:hwdata:d-link:d-link_dir-505 -> Do we need the brand also in the filename?

Current devicepage: http://wiki.openwrt.org/toh/d-link/dir-505
Change dataentry page to -> toh:hwdata:d-link:dir-505 ?

Just asking, havn't thought about that too much yet.

This looks great, although I *was* able to make the Technical Data page creation one step easier :-) The form is now on the template_dataentry page. (Bureaucracy, folded, and hidden plugins make things much easier...)

A couple thoughts:

- Now that there's an automatic process, the page could have (at the bottom), a "Creating a Technical Data Page manually" section.

- I wonder if it's possible to automagically create the Device Details page from the same form. That way, we just tell people, "Just fill in Brand, Model, Version, and Presto! The pages will be set up, and all you have to do is fill them in..."

- Do you know how to modify CSS for the bureaucracy form? It *is* ugly... I'm happy to work on the CSS, if I knew what files to edit.

- Perhaps the Wrap plugin could adjust the form's container, forcing it to look better...

- I made a *lot* of fussy cleanups to the table of field names. You should diff against an earlier version to make sure that I got them correct.

- I moved a lot of the questions to toh:techdatabackground. Some are still outstanding - how shall we resolve them?

Makin' progress, movin' forward, every day, every way.

(Last edited by richbhanover on 10 Jul 2015, 03:43)