@Antek I've seen that you created a bunch of pages regarding developing new software packages for LEDE. Your efforts are highly appreciated!
A proposal to provide the user with a bit of navigation:
We could create a new namespace /docs/guide-developer/helloworld/, where the helloworld_intro would reside in, but named "start", i.e. /helloworld/start. All chapters would also reside in this namespace, i.e. /helloworld/chapter_1 etc.
Benefits:
The namespace helloworld will be displayed in the "You are here" bar on top of the page, enabling the user to easily navigate back to the intro / start page.
We could use a namespace specific sidebar for this namespace, showing all chapters in the menu on the left side
To be honest, I haven't given much thought about the overall navigation system or the final names of the pages, as I was still fleshing out the content of the articles. I made the pages and the initial links in the articles for my own benefit since there was no ability in my Inbox to locate the different articles that were already written, other than directly navigating to them by name.
I can see the logic in your suggestion and agree that it sounds like a good idea. I'll refactor the article structure in my Inbox to reflect this.
Once the content of the articles is ready, we can open a discussion for suggestions on what could/should be changed in the article content so as to make the articles easy to follow and understandable.
Also, maintaining a structure like the one you describe should make it very easy to finally plug the article series to a directory of it's own under the 'guide-developer' section.
EDIT: Is a page named 'start' automatically reachable by navigating to the root folder, or does it need to be explicitly requested? So in a sense, does a page named 'start' function similar to an 'index.html'?
I installed the docnavigation plugin and added the syntax to the pages, including the startpage.
Nice sideeffect: You do no longer need to update the chapter overview on the startpage manually by use of the < doctoc > tag, which does this automatically for all pages in this namespace linked via the docnavigation syntax.
I finished the eight article just now, and I tend to think the series is done for now. At least I can think of anything more to write
Feel free to review the articles and make any changes that you think are necessary. I tried my best to write in a concise manner, but I have absolutely no idea if the LEDE guides should be written in a specific tense or from a certain narrator perspective.
Someone with enough privileges could also consider moving the article series into the 'guide-developer' section. I know I could probably do it myself, too, but moving the articles one-by-one seems like a slow way to do things.
Perhaps my only comments - the build system provides some useful defaults (I know you're using this as an example to make it clearer) For example the Build/Compile target isn't strictly needed if you're not doing anything clever. Maybe mention that and include a pointer to "include/package-defaults.mk' to go find out what the magic defaults are.
But really I cannot stress enough how good & useful this is.
@ldir: By all means, feel free to add comments/pointers like this.
When writing the articles, I did take a cursory look on what all kind of defaults the build system provides, and due to my own lack of understanding of all the intricate black magic that is involved, it was quite a trial and error procedure to get the "progression" part of the article series done in the first place. Due to this, I explicitly chose to explain things in a more verbose manner, and not rely so much on the defaults.
The defaults provided by the build system are very powerful, but since they are not thoroughly, completely and exhaustively documented anywhere (or, I was unable to find such documentation), a new developer is left a little too much to their own devices, trying to figure out "Why does this work the way it does?" Even doubly so if GNU make is even a tad bit foreign for the said developer
Strange "solution": I edited that page, hoping to fix the problem (it didn't), reverted to old status - and it works again.
Wild guess: Might have to do with some caching issues which we seem to experience lately, which express themselves in missing datatables (toh + packages).
I purged the cache of helloworld/start (didn't help), but forgot to do the same for chapter8 before editing the page. Maybe that alone could have solved the problem.
Should you see this again, you can add ?purge=true to the url, or just let me know. We should have an eye on such errors.
Maybe that alone could have solved the problem.